Clone wiki

OpenSauce-Release / Halo1 / Doc_Halo1_NewScriptInterfaces

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:

; 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:

(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.

Updated