From OniGalore
Jump to: navigation, search

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.

Note: BSL will not complain if you use a nonexistent variable for instance in a if condition. However this cause undefined behavior in your scripts (e.g. for instance I had a real case scenario where chr_wait_health did not work as expected) so make sure you always declare the variables that you are using in your scripts.


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.

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
!?: set by engine at game/level load, depends on persist.dat
"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
"OK!": apparently works but makes the game crash/hang/etc. Use with caution if at all.
"??": 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.
bool ai2_chump_stop 0 !!! "stops the chump"
disables the pathfinding behaviour of chump(s)
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)
bool ai2_showdynamicgrids 0 "turns on pathfinding dynamic grid display"
(moving obstacles; needs ai2_showgrids)
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)
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)
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)
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
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)
bool am_invert !? "inverts aiming" This is set from persist.dat at game load (in the absence of persist.dat the default is 0).
The value 0 means normal aiming (mouse up to look up). The value 1 means inverted aiming (mouse down to look up).
bool am_show_axes 0 "shows world axes"
(attaches giant 3D axis to Konoko showing the direction of positive x, y, and z)
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)
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)
bool am_show_texturenames 0 "Shows Texture name"
(displays name of texture you are aiming weapon at, as well as coordinates of reticle)
float character_name_distance 150. "specifies the distance from the camera that character names no longer draw"
(probably needs show_characters)
bool chr_active 1 "enables character activity"
(0 freezes animation etc)
float chr_aim_width 70. "number of degress of aiming width"
width of the aiming arc, in degrees
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
float chr_auto_aim_dist 40. "distance for auto aiming"
upper threshold, in world units
bool chr_big_head 0 !!! "draws everyone with a big head"
(head size set by chr_big_head_amount)
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)
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)
bool chr_debug_fall 0 "controls debugging falling"
(dumps events to console)
bool chr_debug_footsteps 0 "footstep debugging mode"
(dumps events to console)
bool chr_debug_footsteps_verbose 0 "verbose footstep debugging mode"
(dumps anim/type/frame to console)
bool chr_debug_handle 0 "turns on debugging for the handle code"
(dumps events to console)
bool chr_debug_impacts 0 "prints debugging info about character melee impacts"
(to console)
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)
int32 chr_debug_target 0 "selects the character debugging target"
(used by all debugging routines)
bool chr_debug_trigger_quad 0 "controls trigger quad debugging"
(draws characters as vertical lines)
bool chr_disable_melee 0 "turns off all melee damage"
(also disables knockdowns; does NOT disable throws)
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)
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 if disabled)
int32 chr_lod -1 "forces a given lod if it is between 0 and 4"
(uses automatic LOD otherwise)
bool chr_mini_me 0 "decreases the size of the main character"
(custom size set by chr_mini_me_amount below)
float chr_mini_me_amount 0.5 "controls the size of the main character"
(effective only if chr_mini_me is enabled)
The amount can be zero and even negative. If 0 the character becomes invisible. If -1 the character walks below the floor. A lower number like -1000 will also make the character invisible, walk bellow the floor and it will loose the collision with other characters.
bool chr_pin_character 0 "pins a character to the ground"
(freezes the coordinates of all characters)
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)
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)
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)
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 8. "camera canter"
(when not aiming; in degrees)
float cm_canter_weapon 7. "camera canter"
(when aiming, in degrees)
float cm_distance 33. "camera distance"
(to target, in world units)
float cm_height 15. "camera target"
(target height to feet of target character, in world units)
int32 cm_jello_amt 20 "sets the transparency of walls"
(for Jello-cam mode, in % )
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)
int32 co_fade_time 600 "the fade time of the console" OK
bool co_message_display 1 "enables text message display"
(dmsg and prompts)
int32 co_priority 0 "changes the priority of messages to display on the console"
not sure what messages have priority >0
bool debug_consoles 0 "prints debugging information about console usage"
(information about in-game consoles; prints to dev mode console ^^)
bool debug_font_cache 0 "displays font cache texture" ??
bool debug_gun_behavior 0 "enable AI gun behavior debugging"
(dumps events to console)
bool debug_impacts 0 "prints impacts as they occur"
(to console; footsteps, melee, projectiles...)
bool debug_scripts 0 "enable script debugging"
(dumps events to console)
bool debug_triggers 0 "enable trigger volume debugging"
(dumps events to console)
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)
bool draw_every_frame 0 "forces drawing of every frame"
(every draw_every_frame_multipleth frame; takes precedence over fast_mode)
int32 draw_every_frame_multiple 1 "draw every frame multiple"
set drawing frequency if draw_every_frame is ON
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)
int32 env_ray_number 20 "sets the number of rays to cast" (per frame). Bigger values than 20 may be ineffective (cause the console message "allocated too many akira rays") 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 1 "enables fast lookup" ??
bool fast_mode 0 "makes the game run fast" (only if draw_every_frame is disabled) 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)
float gl_fog_end 1. !!! "fog end" in frustum space OK
float gl_fog_green 0.25 !!! "fog green"
(amount: 0 to 1)
float gl_fog_red 0.25 !!! "fog red"
(amount: 0 to 1)
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" (affects the camera movement keys for the free-roaming camera in Dev Mode) OK
int32 gs_screen_shot_reduce 0 "2^n amount of reduction" OK
bool gs_show_characters 1 "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
int32 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)
bool m3_double_buffer 1 "toggles double buffer mode" (may interrupt rendering if disabled! use with caution) 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 ^^ OK!
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)
bool omnipotent 0 !!! "makes player omnipotent" OK
int32 p3_debug_collision 256 "enables collision debugging display"
(actually a boolean; only the low bit counts)
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)
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)
float recoil_base 0.0 "base" (for current ONWC; needs recoil_edit) OK
bool recoil_edit 0 "enables editable recoil"
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"
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)
bool show_flags 0 "enables the display of flags"
bool show_laser_env_collision 0 "draws laser / environment collisions"
(works with any loaded gun)
bool show_patrolpaths 0 "enables the display of AI patrol path objects"
bool show_performance 0 "enables performance display"
(shows FPS counter)
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)
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)
bool show_sound_spheres 0 "sound spheres will always be drawn, not just when a sound sphere is selected"
(environment sounds, see BINA/OBJC/SNDG)
bool show_triggers 1 "enables the display of triggers"
bool show_triggervolumes 0 "Display trigger volumes" OK-D
bool show_turrets 1 "enables the display of turrets"
bool single_step 0 "puts the game in single step mode" (see Developer_Mode#Features for single-step control) 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)
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"
(shows a HUD with info on currently playing sounds; on Macs, sound spheres are also displayed)
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)
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)
float wp_pow_adjustment 0.3 scales crosshair separately (or not, depending on "force" flags) OK
float wp_scale_adjustment 1. adjusts scales OK