BSL:Variables

Variables in BSL are very similar to variables in other programming languages. Here's a brief explanation of what a variable is:

When writing logical programs, one often needs the program to remember some information (a number, a piece of text, the ON/OFF state of a switch, etc) so that the information can be used at a later time.

The usual thing to do in this situation is to store the needed data in a variable: an elementary data container.

General notions

Type and value

A variable (data container) has three important attributes: the name, the type and the value.

The value or the variable is just the contents it currently stores. It can be read and written.

Also, a given variable can store only a specific type of data (floating-point number or integer or text string or boolean), and that is what we call the variable's type.

Finally, the name of a variable is a unique text string that is used to identify the data container within the script. Like function names, variable names are case-sensitive (NOTE: all variables and functions are lower-case). Valid characters are: please fill me in

An easy way to get the type and value of an existing BSL variable is to enter its name at the console in Developer Mode: you typically get console output like "bool: 1" or "int32: 42" or "float: 3.14" or "string: hello"

Declaration and assignment

If you want to use a new variable (data container), you must set it up (declare it) first, with the var keyword. A declaration statement can look a bit like this:

var int my_superduper_integer;
var bool my_totally_awesome_boolean;
var string my_incredible_text_string;
var float my_cool_floating_point_number;

The first word is the keyword "var", next comes the type (keyword), then the name of the variable. The final ";" is required. The name can be any valid name (i.e., not a keyword and not containing invalid characters)

A declaration is usually seen at "global scope" (i.e., outside all functions). It is recommended to group declarations at the beginning of a BSL file (for readability), but it's not necessary. It is also not necessary (but strongly recommended) to declare a variable before the context where it is used for the first time.

On some occasions you may want to declare a local variable (i.e., to embed a declaration statement into a function). This feature will be detailed elsewhere.

Assignment

You can assign a new value to an existing variable with the assignment operator "=". The name of the variable you want to modify is on the left-hand-side (LHS) of the "=", and on the right-hand-side (RHS) you can have any valid expression that evaluates/converts into the variable's type.

An assignment can be combined with a declaration (see above). That means the variable will have a definite value right after it is created. If you don't specify/define such a starting value, you should not, generally speaking, assume anything about the value.

However, apparently there are "default" values assigned to every variable even if it hasn't been defined yet. Those values are 0 (i.e., false) for bool, 0 for int and float, and "" (empty string) for string.

Built-in variables

All the built-in BSL variables are listed here, in alphabetical order.

Color

White: available on all versions

Blue: command only exists in Mac Intel build

Green: command only exists in Windows build

Default value

# !!!: reset by engine at level load (not checked yet for chr_buffer_size and beyond, unless specified)

!?: set by engine at game/level load, depends on persist.dat

Works

"OK": both platforms can use this command

"OK-D": both platforms can use this command, but Windows Oni requires the Daodan DLL

"OK-M": the command only works on Intel Macs

"OK?": confirmation/refinement required

"??": command may not work

"NO": command is proven not to work

Type	Name	Default value	Comment	Works
bool	ai2_barabbas_run	1	"lets Barabbas run while carrying his gun"	OK
bool	ai2_blind	0 !!!	"turns off the AI's visual sensing system"	OK
bool	ai2_boss_battle	0 !!!	"enables AI boss-battle target selection" used in compound: apparently makes Muro's friends focus on yours rather than on you. Only seems to have effect on Boss flagged characters at BINACJBOCharacter file. It seems that makes other characters try to ignore the Boss flagged character and make the Boss flagged character focus on the player rather the other characters.	OK
bool	ai2_chump_stop	0 !!!	"stops the chump" disables the pathfinding behaviour of chump(s)	OK
bool	ai2_deaf	0 !!!	"turns off the AI's sound sensing system"	OK
int32	ai2_debug_localmove_lines	20	"number of lines to cast to debug local-movement code"	OK
bool	ai2_debug_localmovement	0	"debug local-movement code from player's position"	OK
bool	ai2_debug_localpathfinding	0	"debug local-path code from player's position and facing"	OK
bool	ai2_debug_showsettingIDs	0	"shows ID numbers for combat, melee and neutral settings"	??
bool	ai2_ignore_player	0 !!!	"makes all AI ignore the player"	OK
bool	ai2_melee_weightcorrection	1	"weights down non-attack techniques so they are never more than attacks"	??
bool	ai2_printspawn	0	"prints information about each AI spawn"	OK
bool	ai2_showactivationpaths	0	"turns on inactive ==> active pathfinding rendering"	OK
bool	ai2_showastar	0	"shows grid squares that are evaluated by the A* pathfinding"	OK-M
bool	ai2_showcombatranges	0	"shows circles that represent the combat ranges of each AI"	OK
bool	ai2_showconnections	0	"turns on pathfinding connection rendering" (result of a call to ai2_findconnections)	OK
bool	ai2_showdynamicgrids	0	"turns on pathfinding dynamic grid display" (moving obstacles; needs ai2_showgrids)	OK
bool	ai2_showfights	0	"shows fights in progress"	OK?
bool	ai2_showfiringspreads	0	"shows AI firing spread knowledge"	OK
bool	ai2_showgrids	0	"turns on pathfinding grid rendering" (static grids; see AKVA)	OK
bool	ai2_showhealth	0	"draws a health bar for every AI above their head"	OK
bool	ai2_showintersections	0	"debug AI's melee intersections"	??
bool	ai2_showjoblocations	0	"draws a green cross at each AI's job location"	OK?
bool	ai2_showlasers	0	"turns on laser sights for AI2 characters"	??
bool	ai2_showlinetochar	0	"draws a line from the player to every AI"	OK
bool	ai2_showlocalmelee	0	"shows local-environment melee awareness"	OK?
bool	ai2_showlos	0	"shows AI line-of-sight checking" (LOS of all aiming AI leaves a permanent trace)	OK
bool	ai2_shownames	0	"draws the name of every AI above their head"	OK
bool	ai2_showpathfindingerrors	0	"enables visual display of pathfinding errors"	OK?
bool	ai2_showpaths	0	"shows the path each AI is following"	OK
bool	ai2_showprediction	0	"shows prediction info for AI2 characters" (player's "predicted" position is shown etc)	OK
bool	ai2_showprojectiles	0	"shows AI projectile knowledge"	OK
bool	ai2_showsounds	0	"shows AI sounds as they are generated"	OK
bool	ai2_showtargeting	0	"shows targeting info for AI2 characters"	OK
bool	ai2_showvision	0	"shows each AI's vision cones (central and peripheral)"	OK
int32	ai2_spacing_cookies	2	"number of cookies per fight" the more cookies, the more attacks: 0 means nothing but maneuver	OK
bool	ai2_spacing_enable	1	"master enable switch for spacing behavior"	OK?
bool	ai2_spacing_weights	1	"enables position-sensitive weighting of spacing behaviors"	OK?
int32	ai2_stopignoring_count	6	"set the number of events before the AI will stop ignoring"	??
int32	ai2_stopignoring_time	240	"set the delay timer before the AI forgets about ignored events"	??
bool	am_hit_everything	0	"makes the laser pointer hit all objects" (determines whether the gun's aiming laser stops at quads marked with non-object-collision)	OK-M
bool	am_invert	!?	"inverts aiming"	OK
bool	am_show_axes	0	"shows world axes" (attaches giant 3D axis to Konoko showing the direction of positive x, y, and z)	OK-M
bool	am_show_closest	0	"dumps the closest GQ index to console" (continuously prints to console the nearest gunk quad's number followed by two other unhelpful pieces of info)	OK
bool	am_show_filenames	0	"dumps the closest GQ index file/obj name to console" (displays lots of info on-screen, not in console, about quad you are aiming weapon at, but no file names)	OK-M
bool	am_show_texturenames	0	"Shows Texture name" (displays name of texture you are aiming weapon at, as well as coordinates of reticle)	OK
float	character_name_distance	150.	"specifies the distance from the camera that character names no longer draw" (probably needs show_characters)	OK-M
bool	chr_active	1	"enables character activity" (0 freezes animation etc)	OK
float	chr_aim_width	70.	"number of degress of aiming width" width of the aiming arc, in degrees	OK
bool	chr_all_active	0	"forces all characters to be active"	OK
float	chr_auto_aim_arc	90.	"number of degress of auto aiming arc" width of the auto aiming arc, in degrees	OK
float	chr_auto_aim_dist	40.	"distance for auto aiming" upper threshold, in world units	OK
bool	chr_big_head	0 !!!	"draws everyone with a big head" (head size set by chr_big_head_amount)	OK
float	chr_big_head_amount	4.	"Controls the size of the big head"	OK
float	chr_block_angle	20.	"controls the angle at which the characters can block"	OK
int32	chr_buffer_size	8	"0 = normal buffer, otherwise buffer duration"	??
bool	chr_collision_box	1	"toggles character bounding box / bounding sphere collision"	??
float	chr_collision_grow	0.	"sets character bounding box collision grow amount"	??
bool	chr_corpse_fade_offscreen	1	"makes corpses fade when they are offscreen"	??
int32	chr_death_fade_frames	180	"the number of game ticks until charaters fade over"	??
int32	chr_death_fade_start	7200	"the number of game ticks until charaters begin to fade"	??
bool	chr_debug_aiming_screen	0	"turns on aiming screen debugging" (dumps AS changes to console)	OK
bool	chr_debug_characters	0	"enables debugging information for characters"	OK
bool	chr_debug_collision	0	"turns on/off debugging of collision" (melee collision info written to console)	OK
bool	chr_debug_fall	0	"controls debugging falling" (dumps events to console)	OK
bool	chr_debug_footsteps	0	"footstep debugging mode" (dumps events to console)	OK
bool	chr_debug_footsteps_verbose	0	"verbose footstep debugging mode" (dumps anim/type/frame to console)	OK
bool	chr_debug_handle	0	"turns on debugging for the handle code" (dumps events to console)	OK
bool	chr_debug_impacts	0	"prints debugging info about character melee impacts" (to console)	OK
bool	chr_debug_overlay	0	"enables debugging information for overlays"	OK
bool	chr_debug_pathfinding	0	"control pathfinding debugging"	OK
bool	chr_debug_sphere	0	"enables sphere tree debugging for characters" (draws collision spheres for every character)	OK
int32	chr_debug_target	0	"selects the character debugging target" (used by all debugging routines)	OK
bool	chr_debug_trigger_quad	0	"controls trigger quad debugging" (draws characters as vertical lines)	OK
bool	chr_disable_melee	0	"turns off all melee damage" (also disables knockdowns; does NOT disable throws)	OK
bool	chr_disable_visactive	0	"disables visibility activation"	OK
bool	chr_draw_aiming_vector	0	"enables drawing of the aiming vector"	OK
bool	chr_draw_all_characters	0	"forces the drawing of all characters" (also keeps them active)	OK
bool	chr_draw_facing_vector	0	"enables drawing of the facing vector"	OK
bool	chr_draw_weapon	1	"controls drawing of weapons"	OK
bool	chr_enable_collision	1	"enables character collision" (does NOT prevent throws)	OK
int32	chr_lod	-1	"forces a given lod if it is between 0 and 4" (uses automatic LOD otherwise)	OK
bool	chr_mini_me	0	"decreases the size of the main character" (custom size set by chr_mini_me_amount)	OK
float	chr_mini_me_amount	0.5	"controls the size of the main character" (if chr_mini_me is enabled)	OK
bool	chr_pin_character	0	"pins a character to the ground" (freezes coordinates of all chars)	OK
bool	chr_print_sound	0	"turns on printing of the sound effect"	??
bool	chr_show_bnv	0	"shows the bnv of the main character" (pathfinding volume; see AKVA)	OK
bool	chr_show_lod	0	"shows the current lod of the main character"	OK
int32	chr_show_movement	0	"enables movement debugging information for characters" (dumps XZ velocity to console every # frames)	OK
int32	chr_show_weaponid	0	"Shows weapon ID"	OK
bool	chr_showextent_globals	0	"shows the global parts of an attack animation's extent"	OK
bool	chr_weapon_auto_aim	1	"enables auto aiming" (melee auto aiming not affected)	OK
float	cinematic_xoffset	20.	"offset from the vertical edge of the screen for the cinematic insert"	??
float	cinematic_yoffset	65.	"offset from the horizontal edge of the screen for the cinematic insert"	??
float	cm_canter_unarmed	7.	"camera canter" (when not aiming; in degrees)	OK
float	cm_canter_weapon	8.	"camera canter" (when aiming, in degrees)	OK
float	cm_distance	33.	"camera distance" (to target, in world units)	OK
float	cm_height	15.	"camera target" (target height to feet of target character, in world units)	OK
int32	cm_jello_amt	20	"sets the transparency of walls" (for Jello-cam mode, in % )	OK
float	cm_jello_radius	12.	radius of effect of Jello-cam mode	OK
float	cm_lookspring_percent	0.5	"at what percent of lookspring fight mode turns off"	??
bool	cm_plane_test	1	"jello camera plane test"	OK
bool	co_display	1	"enables console display" (console output only)	OK
int32	co_fade_time	600	"the fade time of the console"	OK
bool	co_message_display	1	"enables text message display" (dmsg and prompts)	OK
int32	co_priority	0	"changes the priority of messages to display on the console" not sure what messages have priority >0	OK
1	debug_consoles	0	"prints debugging information about console usage" (information about in-game consoles; prints to dev mode console ^^)	OK
bool	debug_font_cache	0	"displays font cache texture"	??
bool	debug_gun_behavior	0	"enable AI gun behavior debugging" (dumps events to console)	OK
bool	debug_impacts	0	"prints impacts as they occur" (to console; footsteps, melee, projectiles...)	OK
bool	debug_scripts	0	"enable script debugging" (dumps events to console)	OK
bool	debug_triggers	0	"enable trigger volume debugging" (dumps events to console)	OK
bool	debug_weapons	0	"prints debugging info about weapon particle events"	OK
bool	door_drawframes	0	"draws doorframes for all unplaced doors"	??
bool	door_ignore_locks	0	"disables all door locks"	OK
bool	door_pop_lighting	0	"uses bad door lighting"	??
bool	door_show_activation	0	"draws a circle where door activates"	??
bool	door_show_debug	0	"shows debug geometry" (dumps events to console)	OK
bool	draw_every_frame	0	"forces drawing of every frame" (every draw_every_frame_multipleth frame)	OK
int32	draw_every_frame_multiple	1	"draw every frame multiple" set drawing frequency if draw_every_frame is ON	OK
bool	env_collision	1	"enables environment collision"	??
bool	env_drawallgqs	0	"draw all the GQs"	??
bool	env_drawfrustum	0	"draw the frustum around the environment camera"	??
bool	env_drawvisonly	0	"draw only the GQs used for visibility"	??
int32	env_highlight_gq	-1	"highlights a particular gq" (-1 means none)	OK
int32	env_ray_number	20	"sets the number of rays to cast" (per frame?)	OK
bool	env_show_ghostgqs	0	"when true show ghost GQs" (PC&Mac: Works only for self-made GQs via onisplit v0.9.93.0 -create:level in -debug out/*.xml; )	OK
bool	env_show_leafnodes	0	"enables display of environment octtree leaf nodes"	??
bool	env_show_octnode_gqs	0	"when true the environment only renders triangles in the octnode that contains the manual camera"	??
bool	env_show_octtree	0	"enables display of environment octtree traversal"	??
bool	env_show_quad_count	0	"shows the count of visable environment quads"	??
bool	env_show_rays	0	"draw the rays"	??
bool	env_show_stairflagged	0	"show specially flagged noncollision quads" (not sure what this was supposed to do, but the dev keys for "Character collision" (Ctrl-Shift-T) and "Invisible quads" (Ctrl-Shift-I) will show stair collision ramps)	??
bool	fast_lookup	0	"enables fast lookup"	??
bool	fast_mode	0	"makes the game run fast"	OK
float	flag_name_distance	150.0	"specifies the distance from the camera that flag names no longer draw" (probably needs show_flags)	??
int32	flag_new_id	!?	"specifies the id for a new flag" (equal to the last flag added at level load)	??
bool	footstep_flash	0	"footstep flash mode"	OK
float	fx_laser_width	0.2	width of lasers (weapons and triggers)	OK
bool	gl_disable_depth_reads	0	"disable_depth_reads"	??
bool	gl_disable_dxt1	0	"lets you disable use of DXT1"	??
bool	gl_disable_packed_pixels	0	"lets you disable packed-pixels support"	??
float	gl_fog_blue	0.25 !!!	"fog blue" (amount: 0 to 1)	OK
float	gl_fog_end	1. !!!	"fog end" in frustum space	OK
float	gl_fog_green	0.25 !!!	"fog green" (amount: 0 to 1)	OK
float	gl_fog_red	0.25 !!!	"fog red" (amount: 0 to 1)	OK
float	gl_fog_start	0.975 !!!	"fog start" in frustum space	OK
int32	gl_mipmap_offset	0	"lets you disable miplevels (-ve = disable big, +ve = disable small)"	??
float	gs_input_accel	5.0	"use this to control the input sensitivity"	??
int32	gs_screen_shot_reduce	0	"2^n amount of reduction"	OK
bool	gs_show_characters	0	"turns on the drawing of characters"	OK
bool	gs_show_corpses	1	"show corpses"	OK
bool	gs_show_environment	1	"turns on doing the environment"	OK
bool	gs_show_object_count	0	"shows the count of objects"	??
bool	gs_show_objects	1	"turns on the drawing of objects"	OK
bool	gs_show_particles	1	"turns on the drawing of particles"	OK
bool	gs_show_physics_count	0	"shows the count of physics"	??
bool	gs_show_scripting_count	0	"shows the count of active scripting contexts"	??
bool	gs_show_shadows	1	"enables character shadows"	OK
bool	gs_show_sky	1	"turns on the sky"	??
bool	gs_show_ui	1	"turns on the ui" (aka HUD)	OK
bool	gs_sleep	0	"turns on a call to sleep to make debugging easier"	??
bool	gs_stable_ear	1	"makes the ear stable"	??
bool	invincible	0 !!!	"makes player invincible"	OK
bool	laser_alpha	0	WTF? lasers are always transparent	??
bool	li_center_cursor	1	"should we center the cursor"	OK
bool	m3_buffer_clear	1	"toggles buffer clear"	OK
bool	m3_clear_color	0	"color to clear the back buffer to" (color behind skybox) (actually a 32-bit RGB integer; can calculate it with this site)	OK
bool	m3_double_buffer	1	"toggles double buffer mode"	OK
bool	m3_fill_solid	1	"toggles wireframe/solid"	OK
bool	m3_shade_vertex	1	"vertex shader on/off"	OK
bool	m3_texture	1	0 >> crash ^^	??
bool	m3_zcompareon	1	"true if zcompare is on"	OK
bool	marketing_line_off	0	"turns the laser line off"	OK
float	mouse_acceleration	0.75	"sets the mouse acceleration value"	OK
bool	ob_show_debug	0	"enable physics debugging visuals" (shows spheres for doors etc)	OK
bool	omnipotent	0 !!!	"makes player omnipotent"	OK
int32	p3_debug_collision	256	"enables collision debugging display" (actually a boolean; only the low bit counts)	OK
bool	p3_everything_breakable	0	"makes every quad breakable"	OK
bool	p3_furniture_breakable	0	"makes all furniture breakable"	OK
bool	p3_glass_breakable	1	"enables breakable glass"	OK
bool	p3_show_env_collision	0	"draws particle / environment collisions"	OK
float	patrolpath_name_distance	150.0	"specifies the distance from the camera that patrol point names no longer draw" (probably needs show_patrolpaths)	OK-M
bool	ph_active	1	"enable physics"	OK
bool	ph_debug_keyforces	0	"toggle keyboard applied forces"	??
bool	ph_show_collisions	0	"toggle display of colliding quads" (also see show_chr_env_collision)	OK
float	recoil_base	0.0	"base" (for current ONWC; needs recoil_edit)	OK
bool	recoil_edit	0	"enables editable recoil"	OK
float	recoil_factor	0.0	"factor" (for current ONWC; needs recoil_edit)	OK
float	recoil_max	0.0	"factor" (for current ONWC; needs recoil_edit)	OK
float	recoil_return_speed	0.0	"factor" (for current ONWC; needs recoil_edit)	OK
int32	save_point	!?	which save point we are on	OK
int32	saved_film_character_offset	1	"dumps the filmed animation data of the player to file"	OK?
bool	saved_film_loop	0	enables looping when play_recording	OK
string	sc_bind_f2	""	name of animation bound to cutscene1	OK
string	sc_bind_f3	""	name of animation bound to cutscene2	OK
bool	show_characters	0	"enables the display of character starting positions" (see BINA/OBJC/CHAR)	OK-M
bool	show_chr_env_collision	0	"draws character / environment collisions" (shows all quads that character touches, unlike ph_show_collisions which only shows quad you are standing on)	OK
bool	show_flags	0	"enables the display of flags" (see BINA/OBJC/FLAG)	OK-M
bool	show_laser_env_collision	0	"draws laser / environment collisions" (works with any loaded gun)	OK
bool	show_patrolpaths	0	"enables the display of AI patrol path objects" (see BINA/OBJC/PATR)	OK-M
bool	show_performance	0	"enables performance display" (shows FPS counter)	OK
bool	show_performance_gsd	0	??	??
bool	show_performance_gsu	0	??	??
bool	show_sound_all	0	"sound rings will always be drawn, not just when a sound is selected" (environment sounds, see BINA/OBJC/SNDG)	OK-M
bool	show_sound_rectangles	0	"sound rectangles will always be drawn, not just when a sound Rectangle is selected" (environment sounds, see BINA/OBJC/SNDG)	OK-M
bool	show_sound_spheres	0	"sound spheres will always be drawn, not just when a sound Rectangle is selected" (environment sounds, see BINA/OBJC/SNDG)	OK-M
bool	show_triggers	1	"enables the display of triggers" (see BINA/OBJC/TRIG)	OK
bool	show_triggervolumes	0	"Display trigger volumes"	OK-D
bool	show_turrets	1	"enables the display of turrets" (see BINA/OBJC/TURR)	OK
bool	single_step	0	"puts the game in single step mode"	OK
float	sky_height	0.	Y offset of skybox?	??
bool	sky_show_clouds	1	"toggles display of the clouds"	??
bool	sky_show_planet	1	"toggles display of the planet (sun/moon)" (sun present only in levels 2 and 3)	OK
bool	sky_show_sky	1	"toggles display of the sky" (master switch)	OK
bool	sky_show_skybox	1	"toggles display of the skybox"	OK
bool	sky_show_stars	1	"toggles display of the stars" (no stars in any level)	??
bool	sound_show_debug	0	"displays sound debugging info" (do sound spheres show up in Windows, or only the HUD?)	OK
bool	sound_show_occlusions	0	"enables debugging display of sound occlusions" (shows lines from sound sources to listeners)	??
bool	spatial_footsteps	1	"spatial footsteps"	??
bool	sync_debug	0	"enables sync debugging"	??
float	target_max_distance	75000.	"Sets the distance at which the radar will start to change from its minimum"	OK
bool	turret_show_debug	0	"enables the display of turret debug lines"	OK-M
bool	ui_suppress_prompt	0	"suppresses UI prompting about new objectives or moves" (and saved games and training tips and such)	OK
bool	unstoppable	0 !!!	makes player unstoppable	OK
bool	wait_for_key	0	"makes the game wait for a key before level load"	OK
bool	wp_disable_fade	0	"disables weapon fading"	OK
int32	wp_fadetime	360	"sets free time for powerups"	OK-D
bool	wp_force_half_scale	0	crosshairs scale with distance, pow_adjustment redundant	OK
bool	wp_force_no_scale	0	crosshairs don't scale with distance, pow_adjustment ineffective	OK
bool	wp_force_scale	0	crosshairs scale with distance, pow_adjustment ineffective	OK
int32	wp_hypostrength	25	"sets strength of hypo spray" apparently in % of full health, seems hard-coded	??
bool	wp_kickable	0	"lets the player kick weapons" (actually lets everyone but the player collide with guns)	OK
float	wp_pow_adjustment	0.3	scales crosshair separately (or not, depending on "force" flags)	OK
float	wp_scale_adjustment	1.	adjusts scales	OK