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. E.g., 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 (i.e., 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.