Better MS Scripting Reference: header_operations expanded

Currently viewing this thread:

Lav

Sergeant Knight at Arms
M&BWB
If you ever needed a comprehensive reference on Warband Module System operations, you have found it!

Operations introduced in Warband patches 1.153-1.166 are indicated appropriately.

Here you can find a thoroughly restructured, expanded and documented version of header_operations.py file from the Warband Module System. All operations have been grouped into sections, their calling syntax has been checked, nearly every operation has been properly commented. Many mistakes or inconsistencies in operation calling syntax or supposed effects have been researched and corrected. Most unobvious conventions and assumptions are highlighted.

What's more, a lot of comments have been added to the file which should make it much easier to use by people who are still learning the ropes of Warband modding.

Download URL #1: http://www.nexusmods.com/mountandblade/mods/3478
Download URL #2: http://www.mbrepository.com/file.php?id=3478

Updated version at GitLab:

Updated version at mbcommands.fandom:

Code:
################################################################################
#                                               header_operations expanded RC1 #
################################################################################
# TABLE OF CONTENTS
################################################################################
#
# [ Z00 ] Introduction and Credits.
# [ Z01 ] Operation Modifiers.
# [ Z02 ] Flow Control.
# [ Z03 ] Mathematical Operations.
# [ Z04 ] Script/Trigger Parameters and Results.
# [ Z05 ] Keyboard and Mouse Input.
# [ Z06 ] World Map.
# [ Z07 ] Game Settings.
# [ Z08 ] Factions.
# [ Z09 ] Parties and Party Templates.
# [ Z10 ] Troops.
# [ Z11 ] Quests.
# [ Z12 ] Items.
# [ Z13 ] Sounds and Music Tracks.
# [ Z14 ] Positions.
# [ Z15 ] Game Notes.
# [ Z16 ] Tableaus and Heraldics.
# [ Z17 ] String Operations.
# [ Z18 ] Output And Messages.
# [ Z19 ] Game Control: Screens, Menus, Dialogs and Encounters.
# [ Z20 ] Scenes and Missions.
# [ Z21 ] Scene Props and Prop Instances.
# [ Z22 ] Teams and Agents.
# [ Z23 ] Presentations.
# [ Z24 ] Multiplayer And Networking.
# [ Z25 ] Remaining Esoteric Stuff.
# [ Z26 ] Hardcoded Compiler-Related Code.
#
################################################################################

Code:
################################################################################
# [ Z14 ] POSITIONS
################################################################################

  # Positions are the 3D math of the game. If you want to handle objects in
  # space, you will inevitably have to deal with positions. Note that while most
  # position-handling operations work both on global map and on the scenes,
  # there are operations which will only work in one or another mode.

  # Each position consists of three parts: coordinates, rotation and scale.

  # Coordinates are three numbers - (X,Y,Z) - which define a certain point in
  # space relative to the base of coordinates. Most of the time, the base of
  # coordinates is either the center of the global map, or the center of the
  # scene, but there may be exceptions. Note that all operations with
  # coordinates nearly always use fixed point numbers.

  # Position rotation determines just that - rotation around corresponding
  # world axis. So rotation around Z axis means rotation around vertical axis,
  # in other words - turning right and left. Rotation around X and Y axis will
  # tilt the position forward/backwards and right/left respectively.

  # It is common game convention that X world axis points to the East, Y world
  # axis points to the North and Z world axis points straight up. However this
  # is so-called global coordinates system, and more often than not you'll be
  # dealing with local coordinates. Local coordinates are the coordinate system
  # defined by the object's current position. For the object, his X axis is to
  # the right, Y axis is forward, and Z axis is up. This is simple enough, but
  # consider what happens if that object is turned upside down in world space?
  # Object's Z axis will point upwards *from the object's point of view*, in
  # other words, in global space it will be pointing *downwards*. And if the
  # object is moving, then it's local coordinates system is moving with it...
  # you get the idea.

  # Imagine the position as a small point with an arrow somewhere in space.
  # Position's coordinates are the point's position. Arrow points horizontally
  # to the North by default, and position's rotation determines how much was
  # it turned in the each of three directions.

  # Final element of position is scale. It is of no direct relevance to the
  # position itself, and it does not participate in any calculations. However
  # it is important when you retrieve or set positions of objects. In this
  # case, position's scale is object's scale - so you can shrink that wall
  # or quite the opposite, make it grow to the sky, depending on your whim.

# Generic position operations

init_position                               =  701  # (init_position, <position>),
                                                    # Sets position coordinates to [0,0,0], without any rotation and default scale.
copy_position                               =  700  # (copy_position, <position_target>, <position_source>),
                                                    # Makes a duplicate of position_source.
position_copy_origin                        =  719  # (position_copy_origin, <position_target>, <position_source>),
                                                    # Copies coordinates from source position to target position, without changing rotation or scale.
position_copy_rotation                      =  718  # (position_copy_rotation, <position_target>, <position_source>),
                                                    # Copies rotation from source position to target position, without changing rotation or scale.

position_transform_position_to_parent       =  716  # (position_transform_position_to_parent, <position_dest>, <position_anchor>, <position_relative_to_anchor>),
                                                    # Converts position from local coordinate space to parent coordinate space. In other words, if you have some position on the scene (anchor) and a position describing some place *relative* to anchor (for example [10,20,0] means "20 meters forward and 10 meters to the right"), after calling this operation you will get that position coordinates on the scene in <position_dest>. Rotation and scale is also taken care of, so you can use relative angles.
position_transform_position_to_local        =  717  # (position_transform_position_to_local, <position_dest>, <position_anchor>, <position_source>),
                                                    # The opposite to (position_transform_position_to_parent), this operation allows you to get source's *relative* position to your anchor. Suppose you want to run some decision making for your bot agent depending on player's position. In order to know where player is located relative to your bot you call (position_transform_position_to_local, <position_dest>, <bot_position>, <player_position>). Then we check position_dest's Y coordinate - if it's negative, then the player is behind our bot's back.

# Position (X,Y,Z) coordinates

position_get_x                              =  726  # (position_get_x, <destination_fixed_point>, <position>),
                                                    # Return position X coordinate (to the east, or to the right). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).
position_get_y                              =  727  # (position_get_y, <destination_fixed_point>, <position>),
                                                    # Return position Y coordinate (to the north, or forward). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).
position_get_z                              =  728  # (position_get_z, <destination_fixed_point>, <position>),
                                                    # Return position Z coordinate (to the top). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).

position_set_x                              =  729  # (position_set_x, <position>, <value_fixed_point>),
                                                    # Set position X coordinate.
position_set_y                              =  730  # (position_set_y, <position>, <value_fixed_point>),
                                                    # Set position Y coordinate.
position_set_z                              =  731  # (position_set_z, <position>, <value_fixed_point>),
                                                    # Set position Z coordinate.

position_move_x                             =  720  # (position_move_x, <position>, <movement>, [value]),
                                                    # Moves position along X axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) X axis (i.e. whether the position will be moved to it's right/left, or to the global east/west).
position_move_y                             =  721  # (position_move_y, <position>, <movement>,[value]),
                                                    # Moves position along Y axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Y axis (i.e. whether the position will be moved forward/backwards, or to the global north/south).
position_move_z                             =  722  # (position_move_z, <position>, <movement>,[value]),
                                                    # Moves position along X axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Z axis (i.e. whether the position will be moved to it's above/below, or to the global above/below - these directions will be different if the position is tilted).

position_set_z_to_ground_level              =  791  # (position_set_z_to_ground_level, <position>),
                                                    # This will bring the position Z coordinate so it rests on the ground level (i.e. an agent could stand on that position). This takes scene props with their collision meshes into account. Only works during a mission, so you can't measure global map height using this.
position_get_distance_to_terrain            =  792  # (position_get_distance_to_terrain, <destination>, <position>),
                                                    # This will measure the distance between position and terrain below, ignoring all scene props and their collision meshes. Operation only works on the scenes and cannot be used on the global map.
position_get_distance_to_ground_level       =  793  # (position_get_distance_to_ground_level, <position>),
                                                    # This will measure the distance between position and the ground level, taking scene props and their collision meshes into account. Operation only works on the scenes and cannot be used on the global map.

Terms of Use said:
You are free to use this file in your module sources.

You are also free to redistribute the file (separately or as part of your module sources), use the information from the file to create other forms of Module System scripting reference, or convert it to other formats (CHM, HTML, DOC, RTF, PDF, whatever) for as long as you keep "Introduction and Credits" section intact. You can add to it, highlighting your own contribution to the project, but never remove.

The file still could be improved in some places, and not all operations have been completely researched to this moment. Multiplayer section in particular has not been expanded at all, as I do not consider myself an expert on Warband MP modding. Tableau section could use some extra love as well. Some inaccuracies in other sections are also possible, humans do make mistakes after all. Despite all that, I daresay this is the file which will be of great help to any Warband scripter.

Special credits go to cmpxchg8b, Caba'drin, SonKidd, MadVader, dunde, Ikaguia, MadocComadrin, Cjkjvfnby and shokkueibu for their help and support during this file development.
 
Last edited by a moderator:

CTCCoco

Knight at Arms
WBNW
So, if you wanna to move forward, you only use position_move_y?

It looks easier now, because before I believed that you must to calculate the exact coordinates yourself, just like SA-MP (Pawn), MTA:SA, Garry's Mod... etc.

Thanks for this hehe.
 

Lav

Sergeant Knight at Arms
M&BWB
CTCCoco said:
So, if you wanna to move forward, you only use position_move_y?

It looks easy now, because before I believed that you must to calculate the exact coordinates yourself, just like SA-MP (Pawn), MTA:SA, Garry's Mod... etc.

Thanks for this hehe.
Apparently so, though I have not tested this (I'm still preparing the research plan for mission-time operators - that includes positions, agents, scene props and scene items). So test this before using in actual code.

If it doesn't work as advertised, you can still create a position with coords (0, Y, 0) and call position_transform_position_to_parent to get target position.
 

Specialist

Master Knight
WB
Amazing! Too bad replace_scene_props only works in MT triggers though. I could really use a trigger that replaces props at will. :razz:
 

Lav

Sergeant Knight at Arms
M&BWB
Specialist said:
Amazing! Too bad replace_scene_props only works in MT triggers though. I could really use a trigger that replaces props at will. :razz:
Well, moving a prop 1000 meters below ground usually works. Though this method will eventually overload the memory if used frequently. As a way around, you could probably have a "hidden cache" of scene props below ground, where you could take them from when needed. Maybe even make a script which will take a scene prop from the cache if there's one, or create a new if cache has no instances of needed prop left.
 

Swyter

Grandmaster Knight
M&BWBWF&S
Good job, only two comments:

Code:
  # Sooner or later someone was bound to dedicate some time and effort to fix
  # this problem by properly documenting the file. It just so happened that I
  # was the first person crazy enough to accept the challenge.

You're not the first, all these people contributed originally for documenting the opcodes.

Was an idea of the now disappeared Theoris, whom I helped and later maintained the online docs.
In various formats that even allows exporting to the games format.

Code:
http://mbcommands.ollclan.eu/top/

So please, change that.



Here's my personal contribution, maybe I'm not 100% spot on though:

Code:
set_tooltip_text                      = 1130  # (set_tooltip_text, <string_id>),
                                              # Assigns the output text for the selected item?

ai_mesh_face_group_show_hide          = 1805  # (ai_mesh_face_group_show_hide, <group_no>, <value>), # 1 for enable, 0 for disable
                                              # Debug -- Draws the selected index of triangles/quads from the navigation graph on-screen.
											  
auto_set_meta_mission_at_end_commited = 1305  # (auto_set_meta_mission_at_end_commited), Not documented. Not used in Native. Was (simulate_battle, <value>) before.
                                              # Returns the mission as successful by the game. Used in campaign.
 

Lav

Sergeant Knight at Arms
M&BWB
Swyter said:
Good job, only two comments:
You're not the first, all these people contributed originally for documenting the opcodes.

Was an idea of the now disappeared Theoris, whom I helped and later maintained the online docs.
In various formats that even allows exporting to the games format.

Code:
http://mbcommands.ollclan.eu/top/

So please, change that.
I think we mean different challenges here. My goal was to get the job done. Not to contribute, not to create a tool to aggregate community contributions, but simply to get the job done - alone if necessary. So while MB Commands Database is an attempt to achieve the same goal, it is an entirely different challenge.

Swyter said:
Here's my personal contribution, maybe I'm not 100% spot on though:

Code:
set_tooltip_text                      = 1130  # (set_tooltip_text, <string_id>),
                                              # Assigns the output text for the selected item?

ai_mesh_face_group_show_hide          = 1805  # (ai_mesh_face_group_show_hide, <group_no>, <value>), # 1 for enable, 0 for disable
                                              # Debug -- Draws the selected index of triangles/quads from the navigation graph on-screen.
											  
auto_set_meta_mission_at_end_commited = 1305  # (auto_set_meta_mission_at_end_commited), Not documented. Not used in Native. Was (simulate_battle, <value>) before.
                                              # Returns the mission as successful by the game. Used in campaign.
Thanks!
 

Swyter

Grandmaster Knight
M&BWBWF&S
wadlegnst said:
Thanks for this hehe.



g.gif

You can find an updated version here:
Code:
https://bitbucket.org/Swyter/swysdk/src/76c918857aa3/Header/header_operations.py

I've added all the new opcodes until the newest v1.153. You probably have to remove a bunch of
Code:
swysdk
and
Code:
wse
related code.

_______________
PS: What's with the beacon image you insert at the end of all your posts, wadlegnst?
Code:
[IMG]http://www.dailyforexrates.info/g.gif[/IMG]
[size=8pt]

Is it some sort of dishonest tracking, exploit or advertising?  :neutral:
 

Lav

Sergeant Knight at Arms
M&BWB
Brought up to date with version 1.153 operations.

UPDATE: Removed the MediaFire link, added Nexus instead.
 

shokkueibu

Knight
M&BWB
Excellent work, Lav :smile:

Here's some stuff for you:
[font=consolas,courier]player_is_active[/font] - Checks that the player reference corresponds to active player. Players are assigned a free ID after connection and on disconnection it becomes free/invalid until taken by another connecting player.
[font=consolas,courier]multiplayer_is_server[/font] - Checks that the game running is a server. This will succeed for listen and dedicated servers and will only fail on clients.
[font=consolas,courier]multiplayer_is_dedicated_server[/font] - Checks that the game running is a dedicated server. This will only succeed for dedicated servers and will fail on listen servers and clients.
[font=consolas,courier]player_is_admin[/font] - Checks that the player used the admin password to join the server .
[font=consolas,courier]player_is_busy_with_menus[/font] - Unconfirmed, educated guess. Checks if the referenced player is on a presentation without the [font=consolas,courier]prsntf_read_only[/font] flag.
[font=consolas,courier]player_item_slot_is_picked_up[/font] - Checks that the provided item slot for the referenced player was picked up from the battlefield instead of bought.

[font=consolas,courier]send_message_to_url[/font] - Accesses the the URL in the provided string.
The result will be returned to [font=consolas,courier]script_game_receive_url_response[/font].
If [font=consolas,courier]encode_url[/font] is 1 it will do the same as [font=consolas,courier]str_encode_url[/font] ( percent-encoding).


[font=consolas,courier]multiplayer_send_message_to_server
multiplayer_send_int_to_server   
multiplayer_send_2_int_to_server 
multiplayer_send_3_int_to_server 
multiplayer_send_4_int_to_server 
[/font]
Sends from 0 to 4 integers to the server. Is called on the client.

[font=consolas,courier]multiplayer_send_string_to_server[/font]
Sends a single string to the server. Is called on the client.

The [font=consolas,courier]message_type[/font] parameter must be between 0 and 127 or it will be truncated.
In the case of Native they can be found on header_common.py as client and server events.

These are handled in [font=consolas,courier]script_game_receive_network_message[/font] and are used for server events.

The other 6 operations ([font=consolas,courier]multiplayer_send_*_to_player[/font]) have the same functionality but are called on the server and send the message to the player referenced by [font=consolas,courier]player_id[/font].


[font=consolas,courier]player_get_team_no[/font] - Retrieves the team that the player belongs to.
[font=consolas,courier]player_set_team_no[/font] - Puts the player to specified team number
[font=consolas,courier]player_get_troop_id[/font] - Retrieves the troop type of the specified player.
[font=consolas,courier]player_set_troop_id[/font] - Defines the troop type of the specified player.
[font=consolas,courier]player_get_agent_id[/font] - Retrieves the agent reference of the specified player.
[font=consolas,courier]player_get_gold[/font] - Retrieves the gold amount of the specified player.
[font=consolas,courier]player_set_gold[/font] - Defines the gold amount of the specified player. Set max_value to 0 if no limit is desired.
[font=consolas,courier]player_spawn_new_agent[/font] - Spawns a new agent on the specified entry point. The agent is created from the troop of the specified player.
[font=consolas,courier]player_add_spawn_item[/font] - Adds the specified item to the specified player. Will take effect after the next [font=consolas,courier]player_spawn_new_agent[/font].
Available item slots are: [font=consolas,courier]ek_item_0, ek_item_1, ek_item_2, ek_item_3, ek_head, ek_body, ek_foot, ek_gloves, ek_horse[/font].
Unsure if [font=consolas,courier]ek_food[/font] is used in multiplayer; Taken from header_items.py
[font=consolas,courier]multiplayer_get_my_team[/font] - Retrieves the current team of the player. Only works client side.
[font=consolas,courier]multiplayer_get_my_troop[/font] - Retrieves the current troop of the player. Only works client side.
[font=consolas,courier]multiplayer_set_my_troop[/font] - Defines the current troop of the player. Only works client side.
[font=consolas,courier]multiplayer_get_my_gold[/font] - Retrieves the gold amount of the player. Only works client side.
[font=consolas,courier]multiplayer_get_my_player[/font] - Retrieves the reference to the player. Only works client side.
 

Lav

Sergeant Knight at Arms
M&BWB
Updated to include the new operation from 1.157 patch. Not that much of an update really. :smile:
 

dunde

Count
WB
Last time I download the file, overlay_set_tooltip is still marked as unknown operation.
I found that (overlay_set_tooltip, <overlay_id>, <string_id>), will make something like hint on windows if we make the mouse pointer stay for a while on the overlay.

Ex:
(overlay_set_tooltip, "$ok_button", "@Click to apply the change and quit the presentation"),
 

Lav

Sergeant Knight at Arms
M&BWB
Yep, thanks. Probably a new version is in order, there were a few other contributions, and I might have learned a bit more about some operations as well.
 

Lav

Sergeant Knight at Arms
M&BWB
This file is part of the Module System. So you need the Module System and everything that goes with it.
 
Top Bottom