Skip to content

Doc_Halo1_NewScriptInterfaces

Jump to bottom
Martin Ballantyne edited this page Mar 2, 2015 · 2 revisions

Introduction

For Halo1_CE, we've added some new external script functions and globals. By external, I mean stuff which isn't defined in your scenario. Eg, object_create is an external script function.

Compatibility with non-OS games

The stock game is not compatible with any maps which use any functions or globals that are not already defined within its code. Thus, custom script definitions require the use enabling of use-memory-upgrades in the build-cache-file-ex tool command. Maps which use incompatible features (ie, features which will crash the game when not running OS) use the .yelo extension instead of the normal .map.

We've setup OS to expose its version in the real global ai_debug_path_maximum_radius. For all OS-specific functions/globals which you access, you need to wrap them in a block of code which first checks that this global isn't zero, or below the supported OS version of what you're dealing with:

#!lisp
; 3.0 is the value of K_OPENSAUCE_VERSION at the time of this writing
(global boolean is_os_enabled (>= ai_debug_path_maximum_radius 3.0) ) </code>

Alternatively, you should be also able to do the following
<code language="lisp">
(script static boolean is_os_enabled
  (>= ai_debug_path_maximum_radius 3.0)
)

However, it is recommended you use the script global method (this can enable OS, in the future, to kill problem scripts due to unrecoverable changes, etc)

Example of using these checks:

#!lisp
(script startup main
  (if is_os_enabled ; if using the global method
    ; Then
    (print "Running OpenSauce!")

    ; Else
    (print "Not running OpenSauce :|")
  )


  (if (is_os_enabled) ; if using the script method
    ; Then
    (print "Running OpenSauce!")

    ; Else
    (print "Not running OpenSauce :|")
  )
)

External Script Functions/Globals

PLAYER SCRIPTING INTERFACE

volume_test_player_team

returns true if any players of the specified team are within the specified volume

Field | Name | Help

  • | - | - return-type | boolean | trigger_volume | trigger_volume | short | team_index |

volume_test_player_team

returns true if all players of the specified team are within the specified volume

Field | Name | Help

  • | - | - return-type | boolean | trigger_volume | trigger_volume | short | team_index |

player_team_teleport

moves the specified team to the specified flag

Field | Name | Help

  • | - | - return-type | void | short | team_index | cutscene_flag | cutscene_flag |

player_team_players

returns a list of players on the specified team

Field | Name | Help

  • | - | - return-type | object_list | short | team_index |

player_data_get_integer

returns an integer value property of the player

Field | Name | Help

  • | - | - return-type | long | -1 if this fails short | player_list_index | string | data_name | kills_this_lifetime, friendly_fire_kills, deaths, suicides, team_index, current_spree_count, last_kill_time, ping

player_team_data_get_integer

returns an integer value of all the players on the team

Field | Name | Help

  • | - | - return-type | long | -1 if this fails short | team_index | string | data_name | kills_this_lifetime, friendly_fire_kills, deaths, suicides

player_data_get_object

returns an object value property of the player

Field | Name | Help

  • | - | - return-type | object | none if this fails short | player_list_index | string | data_name | nearest_object, slave_unit, last_slave_unit, target_player, weapon0 to 3

player_data_get_real

returns a real value property of the player

Field | Name | Help

  • | - | - return-type | real | -1.0 if this fails short | player_list_index | string | data_name | speed

player_data_set_real

sets a real value property of the player

Field | Name | Help

  • | - | - return-type | void | short | player_list_index | string | data_name | speed real | data_value |

player_local_get

returns the local player's player-list-index

Field | Name | Help

  • | - | - return-type | short | -1 if this fails (eg, no active local players)

OBJECT SCRIPTING INTERFACES

objects_distance_to_object

returns minimum distance from any of the specified objects to the specified destination object

Field | Name | Help

  • | - | - return-type | real | -1 if there are no objects to check object_list | objects | object | dst_object | destination object

object_data_get_real

returns a real value property of the object

Field | Name | Help

  • | - | - return-type | real | -1.0 if this fails object | object | string | data_name | position, transitional_velocity, forward, up, angular_velocity, center, function_out, radius, scale, maximum_health, maximum_shield, current_health, current_shield string | subdata_name | x/i, y/j, z/k or a, b, c, d

object_data_set_real

sets a real value property of the object DOES NOTHING IN NETWORKED GAMES IF REQUESTED PROPERTY DOESN'T SYNC

Field | Name | Help

  • | - | - return-type | void | object | object | string | data_name | position, transitional_velocity, forward, up, angular_velocity, maximum_health, maximum_shield, current_health, current_shield string | subdata_name | x/i, y/j, z/k real | data_value |

weapon_data_get_real

returns a real value property of the weapon

Field | Name | Help

  • | - | - return-type | real | -1.0 if this fails object | weapon | string | data_name | heat, age, light_power

weapon_data_set_real

sets a real value property of the weapon. DOES NOTHING IN NETWORKED GAMES IF REQUESTED PROPERTY DOESN'T SYNC

Field | Name | Help

  • | - | - return-type | void | object | weapon | string | data_name | heat, age, light_power real | data_value |

weapon_data_trigger_set_real

sets a real value property of a weapon's trigger. DOES NOTHING IN NETWORKED GAMES

Field | Name | Help

  • | - | - return-type | void | object | weapon | long | trigger_index|| string | data_name | spew_time, rounds_per_second string | subdata_name | lower, upper real | data_value |

unit_data_get_object

returns an object value property of the unit

Field | Name | Help

  • | - | - return-type | object | none if this fails object | unit | string | data_name | weapon0 to 3, recent_damage.unit0 to 3, thrown_grenade_projectile, equipment, damage_responsible_flamer_object

unit_data_get_integer

returns an integer value property of the unit

Field | Name | Help

  • | - | - return-type | long | -1 if this fails unit | unit | string | data_name | total_grenade_count[plasma], total_grenade_count[frag], total_grenade_count[custom2], total_grenade_count[custom3], current_grenade_index, vehicle_seat_index, current_weapon_index, feign_death_timer, zoom_level, ticks_until_flame_to_death, killing_spree_count

unit_data_set_integer

sets an integer value property of the unit. DOES NOTHING IN NETWORKED GAMES IF REQUESTED PROPERTY DOESN'T SYNC

Field | Name | Help

  • | - | - return-type | void | unit | unit | string | data_name | total_grenade_count[plasma], total_grenade_count[frag], total_grenade_count[custom2], total_grenade_count[custom3], desired_zoom_level long | data_value |

unit_data_get_real

returns a real value property of the unit

Field | Name | Help

  • | - | - return-type | real | -1.0 if this fails unit | unit | string | data_name | camo_power, driver_power, gunner_power, integrated_light_power, integrated_light_toggle_power, integrated_night_vision_toggle_power, full_spectrum_vision_power

unit_data_set_real

sets a real value property of the unit. DOES NOTHING IN NETWORKED GAMES

Field | Name | Help

  • | - | - return-type | void | unit | unit | string | data_name | camo_power, driver_power, gunner_power, integrated_light_power, integrated_light_toggle_power, integrated_night_vision_toggle_power, full_spectrum_vision_power real | data_value |

PHYSICS

physics_get_gravity

get the current global gravity acceleration relative to halo standard gravity

Field | Name | Help

  • | - | - return-type | real |

physics_set_gravity

set global gravity acceleration relative to halo standard gravity

Field | Name | Help

  • | - | - return-type | void | real | gravity_fraction |

physics_constants_reset

resets all physics constants to earthly values

Field | Name | Help

  • | - | - return-type | void |

RUNTIME DATA SCRIPTING INTERFACE

As of this writing, OS supports up to 64 'runtime integers/vectors'. These are stored within the game state, so they persist when the game is saved

runtime_integers_reset

reset ALL runtime integers back to zero

Field | Name | Help

  • | - | - return-type | void |

runtime_integer_get

get the runtime integer's current value

Field | Name | Help

  • | - | - return-type | long | value_index | short |

runtime_integer_set

set the runtime integer's current value, returning its previous value

Field | Name | Help

  • | - | - return-type | void | value_index | short | value | long |

runtime_integer_inc

return the runtime integer's current value, then increments the value (aka post-increment)

Field | Name | Help

  • | - | - return-type | void | value_index | short |

runtime_integer_dec

return the runtime integer's current value, then decrements the value (aka post-decrement)

Field | Name | Help

  • | - | - return-type | void | value_index | short |

runtime_integer_operation

perform an operation on a runtime integer

Field | Name | Help

  • | - | - return-type | long | result of operation value_index | short | operation_name | string | =, +=, -=, *=, /=, ++, --, &=, |=, ^=, <<=, >>=, +, -, *, /, &, |, ^, <<, >> operation_value | short | not required for ++ or --

runtime_vectors_reset

reset ALL runtime vectors back to zero

Field | Name | Help

  • | - | - return-type | void |

runtime_vector_get_element

get the runtime vectors's current value

Field | Name | Help

  • | - | - return-type | real | value_index | short | element_index | short | 0,1,2

runtime_vector_set_element

set the runtime vector's element value

Field | Name | Help

  • | - | - return-type | boolean | true if successful value_index | short | element_index | short | 0, 1, 2 operation_name | string | =, +=, -=, *=, /= value | real |

runtime_vector_set

set the runtime vector's elements

Field | Name | Help

  • | - | - return-type | boolean | true if successful value_index | short | operation_name | string | =, +=, -=, *=, /= value_x | real | value_y | real | value_z | real |

runtime_vector_operation

perform an operation on a runtime vector NOTE: dot_product and magnitude set the result value to operation_vector_index's 'x' (ie, 0th) element

Field | Name | Help

  • | - | - return-type | boolean | true if successful value_index | short | operation_name | string | +=, -=, *=, /=, normalize, inverse, conjugate, cross_product, dot_product, scalar_mul, scalar_div, magnitude operation_vector_index | short | not required for normalize or inverse

runtime_vector_to_string

returns the vector in a string as 'x y z', or an empty string if this fails

Field | Name | Help

  • | - | - return-type | string | value_index | short |

object_data_set_vector

set an object's vector field using an existing runtime-vector. DOES NOTHING IN NETWORKED GAMES IF REQUESTED PROPERTY DOESN'T SYNC

Field | Name | Help

  • | - | - return-type | boolean | true if successful object | object | string | data_name | position, transitional_velocity, forward, up, angular_velocity, center vector_index | short | source vector

object_data_save_vector

save an object's vector field to an existing runtime-vector

Field | Name | Help

  • | - | - return-type | boolean | true if successful object | object | string | data_name | position, transitional_velocity, forward, up, angular_velocity, center vector_index | short | destintation vector

GAME ENGINE

game_change_version_id

Field | Name | Help

  • | - | - return-type | boolean | true if the change was successful also-change-game-build-string | boolean | version-string | string | "1.00", "1.07", "1.08", "1.09"

game_engine_data_get_integer

returns an integer value property of the current game engine

Field | Name | Help

  • | - | - return-type | long | -1 if this fails data_name | string | see table below
Valid data_name's

Engine | data_name | Help

  • | - | - All | type | 0=None, 1=CTF, 2=Slayer, 3=Oddball, 4=King, 5=Race All | is_teams | 0=false, 1=true All | is_odd_man_out | 0=false, 1=true All | lives | All | score_to_win | Oddball | oddball:ball_count |

MACHINE/SERVER UTILS

machine_is_host

returns whether or not the local machine is the host

Field | Name | Help

  • | - | - return-type | boolean |

machine_is_dedi

returns whether or not the local machine is a dedicated server

Field | Name | Help

  • | - | - return-type | boolean |

BIT OPERATIONS

bitwise_and

AND 'value' with 'flags'

Field | Name | Help

  • | - | - return-type | long | value | long | flags | long |

bitwise_or

OR 'value' with 'flags'

Field | Name | Help

  • | - | - return-type | long | value | long | flags | long |

bitwise_xor

XOR 'value' with 'flags'

Field | Name | Help

  • | - | - return-type | long | value | long | flags | long |

bitwise_lhs

Bit-shift (to the left) 'value' by 'bit_count'

Field | Name | Help

  • | - | - return-type | long | Returns 0 if count is out of range value | long | flags | bit_count | Any value between 0 and 31, inclusive

bitwise_rhs

Bit-shift (to the right) 'value' by 'bit_count'

Field | Name | Help

  • | - | - return-type | long | Returns 0 if count is out of range value | long | flags | bit_count | Any value between 0 and 31, inclusive

bit_test

Test whether 'value' has a certain bit set

Field | Name | Help

  • | - | - return-type | boolean | Returns false if index is out of range value | long | bit_index | short | Any value between 0 and 31, inclusive

bit_toggle

Turns on or off the bit at 'bit_index' in 'value'

Field | Name | Help

  • | - | - return-type | false | Returns false if index is out of range value | long | bit_index | short | Any value between 0 and 31, inclusive on_or_off | boolean | as in true_or_false

bit_flags_test

Test whether 'value' has a certain bit set

Field | Name | Help

  • | - | - return-type | boolean | Returns false if index is out of range value | long | flags | long |

bit_flags_toggle

Adds or removes 'flags' to or from 'value'

Field | Name | Help

  • | - | - return-type | long | Returns 0 if index is out of range value | long | flags | long | on_or_off | boolean | as in true_or_false

MISC

display_scripted_ui_widget

displays the ui widget

Field | Name | Help

  • | - | - return-type | boolean | returns true if successful widget_name | string | name of the widget as it appears in the yelo tags. searches the scenario's yelo first, then globals

play_bink_movie

players a .bik file (must be in the same folder as the game's bik files)

Field | Name | Help

  • | - | - return-type | void | filename | string |

hex_string_to_long

converts a hex string (eg, 'DEADBEEF') to an integer

Field | Name | Help

  • | - | - return-type | long | value | string |

abs_integer

return the absolute (non-negative) value of an integer

Field | Name | Help

  • | - | - return-type | long | value | long |

abs_real

return the absolute (non-negative) value of a real

Field | Name | Help

  • | - | - return-type | real | value | real |

RASTERIZER

rasterizer_rt_display

Global variable used to display the contents of the GBuffer. -1 = all buffers, 0 = no display, 1 = depth, 2 = velocity, 3 = normals (-1 to 1), 4 = normals (0 to 1), 5 = index.

Field | Name | Help

  • | - | - short | rasterizer_rt_display |

rasterizer_gbuffer_enabled

Global variable used to disable/enable the GBuffer. DO NOT use this in your maps scripts. This is only to be used by the end user if they have issues with performance.

Field | Name | Help

  • | - | - bool | rasterizer_gbuffer_enabled |

rasterizer_model_normal_mapping

Global variable used to toggle model normal mapping on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_model_normal_mapping |

rasterizer_model_detail_normal_mapping

Global variable used to toggle model detail normal mapping on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_model_detail_normal_mapping |

rasterizer_model_specular_lights

Global variable used to toggle model specular lighting on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_model_specular_lights |

rasterizer_model_specular_map

Global variable used to toggle model specular color mapping on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_model_specular_map |

rasterizer_environment_dlm_diffuse

Global variable used to toggle diffuse directional lightmaps on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_environment_dlm_diffuse |

rasterizer_environment_dlm_specular

Global variable used to toggle specular directional lightmaps on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_environment_dlm_specular |

rasterizer_effect_depth_fade

Global variable used to toggle effect depth fading on and off. This does not affect your OS settings. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | rasterizer_effect_depth_fade |

POSTPROCESSING

pp_external_post_processes_enabled

Global variable used to enable/disable external post processes. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | pp_external_post_processes_enabled |

pp_internal_post_processes_enabled

Global variable used to enable/disable internal post processes. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | pp_internal_post_processes_enabled |

pp_fxaa_enabled

Global variable used to enable/disable FXAA. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | pp_fxaa_enabled |

pp_motion_blur_enabled

Global variable used to enable/disable motion blur. DO NOT use this in your maps scripts. This is only to be used by the end user if they have issues with performance.

Field | Name | Help

  • | - | - bool | pp_motion_blur_enabled |

pp_motion_blur_amount

Global variable used to control the amount of motion blur. DO NOT use this in your maps scripts.

Field | Name | Help

  • | - | - bool | pp_motion_blur_amount |

pp_load

Reloads the post processing system after an unload. DO NOT use this in your maps scripts, it is to be used only as a console function!

Field | Name | Help

  • | - | - returns | void |

pp_unload

Unloads the entire post processing system. DO NOT use this in your maps scripts, it is to be used only as a console function!

Field | Name | Help

  • | - | - return-type | void |

pp_get_effect_instance_index_by_name

Returns the index of the effect instance by name

Field | Name | Help

  • | - | - return-type | short | -1 if there is no matching effect instance string | instance_name |

pp_set_effect_instance_active

Turns an effect instance on or off. If an effect instance is set to be not initially enabled, this is the only way to enable the instance.

Field | Name | Help

  • | - | - return-type | void | short | instance_index | boolean | instance_enabled | True to enable the effect, false to disable

pp_set_effect_instance_fade

This function will fade the result of an effect instance in or out. The function takes the instance index, the fade amount to start at and end at (between 0.0 and 1.0), and the length of time the fade should take. If fade-start and fade-end are equal, or fade-time is zero, the end fade amount will be applied immediately. Fading the effect between 0.0 and 1.0 requires a built in post process to be used and incurs a minor performance hit, however once the fade is at 0.0 or 1.0 the built in post process is no longer used.

Field | Name | Help

  • | - | - return-type | void | short | effect_index | real | fade_start | The fade amount to start fading in/out from. Between 0.0f and 1.0f. real | fade_end | The fade amount to start fading in/out to. Between 0.0f and 1.0f. real | fade_time | The amount of time in seconds (approximate) that the fade should take.

pp_get_effect_instance_current_fade

Returns the current fade amount of an effect instance.

Field | Name | Help

  • | - | - return-type | real | short | instance_index |

pp_get_effect_instance_fade_direction

Returns the current fade direction of an effect instance.

Field | Name | Help

  • | - | - return-type | short | -1 = not fading, 0 = fading out, 1 = fading in short | instance_index |

pp_get_effect_index_by_name

Returns the index of a post process effect by name

Field | Name | Help

  • | - | - return-type | short | -1 if there is no matching effect string | effect_name |

pp_get_effect_is_valid

Returns true if the effect is correct and ready for use. If an effect is broken for some reason the function returns false. For example, this could occur when a shader in the effect uses a shader model higher than the players graphic card can support.

Field | Name | Help

  • | - | - return-type | boolean | short | effect_index |

pp_get_effect_shader_variable_index_by_name

Returns the index of a scripted shader variable in a defined effect by name.

Field | Name | Help

  • | - | - return-type | short | -1 if there is no matching scripted variable short | effect_index | string | variable_name |

pp_set_effect_shader_variable_boolean

Sets the value of a scripted boolean variable.

Field | Name | Help

  • | - | - return-type | void | short | effect_index | short | variable_index | boolean | value | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_set_effect_shader_variable_integer

Sets the value of a scripted integer variable.

Field | Name | Help

  • | - | - return-type | void | short | effect_index | short | variable_index | long | value | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_set_effect_shader_variable_real

Sets the value of a scripted integer variable. This function is used for float, float2, float3, float4 and color variables. Use 0.0 for channels you do not need to set.

Field | Name | Help

  • | - | - return-type | void | short | effect_index | short | variable_index | real | float1 | real | float2 | real | float3 | real | float4 | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_set_effect_shader_instance_active

Turn a specific shader instance in an effect on or off.

Field | Name | Help

  • | - | - return-type | void | short | effect_index | short | instance_index | boolean | instance_enabled | True to enable the instance, false to disable.

pp_bloom_set_size

Changes the blur size of the bloom post process.

Field | Name | Help

  • | - | - return-type | void | real | size | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_bloom_set_exposure

Changes the exposure value of the bloom post process. The bloom result is multiplied by this.

Field | Name | Help

  • | - | - return-type | void | real | exposure | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_bloom_set_mix_amount

Changes the mix amount of the bloom post process. This interpolates between no bloom and full bloom.

Field | Name | Help

  • | - | - return-type | void | real | mix_amount | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_bloom_set_minimum_color

Changes the minimum color value of the bloom post process. Colors below this value have no bloom.

Field | Name | Help

  • | - | - return-type | void | real | red | real | green | real | blue | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

pp_bloom_set_maximum_color

Changes the maximum color value of the bloom post process. Colors above this value are fully bloomed.

Field | Name | Help

  • | - | - return-type | void | real | red | real | green | real | blue | real | change_time | Time in seconds (approx.) to change from the current value to the new value.

BSP MODIFIERS

structure_bsp_set_lightmap_set

Set's the lightmaps to use on a BSP.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if the bsp's lightmaps were set to the specified lightmap set. short | bsp-index | The index of the BSP to change. string | set-name | The name of the lightmap set to switch to.

structure_bsp_set_sky_set

Set's the skies to use on a BSP.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if the bsp's skies were set to the specified sky set. short | bsp-index | The index of the BSP to change. string | set-name | The name of the sky set to switch to.

ACTOR VARIANT TRANSFORMS

ai_transforms_enabled

Global variable used to toggle whether actor variant transforms can occur automatically. Transforms can still be triggered using HS if this is false.

Field | Name | Help

  • | - | - bool | ai_transforms_enabled |

ai_transform_actor

Transforms an actor into the specified target. Returns false if it fails. Empty names causes random selection.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if the actor's transform was triggered. object | object | The object to transform. If the object is not an actor the function will fail. string | transform_name | The name of the transform to use. Corresponds to the transform name in the collection tag. If empty a random applicable transform will be used. string | target_name | The name of the target to use. Corresponds to the target name in the transform_in tag. If empty a random target will be used.

ai_transform_actors

Transforms a list of actors into the specified target. Returns false if no transform was triggered. Empty names causes random selection.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if any actor's transform was triggered. object_list | objects | The objects to transform. string | transform_name | The name of the transform to use. Corresponds to the transform name in the collection tag. If empty a random applicable transform will be used. string | target_name | The name of the target to use. Corresponds to the target name in the transform_in tag. If empty a random target will be used.

ai_transform_actors_by_type

Transforms actors in a list of a specific type into the specified target. Returns false if no transform was triggered. Empty names causes random selection.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if any actor's transform was triggered. object_list | objects | The objects to transform. actor_variant | actor_variant | The type of actors to transform. string | transform_name | The name of the transform to use. Corresponds to the transform name in the collection tag. If empty a random applicable transform will be used. string | target_name | The name of the target to use. Corresponds to the target name in the transform_in tag. If empty a random target will be used.

ai_actor_is_transforming

Returns true if the specified actor is transforming.

Field | Name | Help

  • | - | - return-type | bool | The function returns true if the actor is transforming. object | object | The object to check.
Clone this wiki locally