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: preset variables and functions are all 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.
More
Later.
Preset variables
- All the preset OSL variables are listed here, in alphabetical order.
- Please fill in with ssg's stuff (descriptions + OK if variable works).
- Type and default value (from console) if you're motivated enough.
- It may be a little less tedious to expand specific subpages of Preset
- (mini-tutorials of sorts) geyser
- Color
- White : available on all versions
- Gray : available only on PC retail and Mac beta 4
- Red : Mac beta 4 exclusive
- Green : PC retail exclusive
- 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?" means confirmation/refinement required.
Type | Name | Default value | Comment | Works |
---|---|---|---|---|
bool | ai2_barabbas_run | 1 | "lets Barabbas run while carrying his gun" WTF? all AI can always run with the WMC |
?? |
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 |
?? |
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" | ?? |
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" | ?? |
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" | ?? |
bool | am_invert | !? | "inverts aiming" | OK |
bool | am_show_axes | 0 | "shows world axes" | ?? |
bool | am_show_closest | 0 | "dumps the closest GQ index to console" | ?? |
bool | am_show_filenames | 0 | "dumps the closest GQ index file/obj name to console" WTF? shows debug box, but doesn't dump anything |
?? |
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) |
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 zise 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" (pathfindng 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 |
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 mode, in % ) |
OK |
float | cm_jello_radius | 12. | radius of effect of Jello 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" | ?? |
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 ingame consoles; prints to dev mode console ^^) |
OK |
?? | debug_font_cache | ?? | ?? | ?? |
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" | 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" | ?? |
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" | ?? |
?? | gl_disable_dxt1 | ?? | ?? | ?? |
?? | gl_disable_packed_pixels | ?? | ?? | ?? |
float | gl_fog_blue | 0.25 !!! | "fog blue" (amount: 0 to 1) |
OK |
float | gl_fog_end | 1. !!! | "fog end" | 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" | OK |
?? | gl_mipmap_offset | ?? | ?? | ?? |
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 | ?? | ?? |
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 |
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) |
?? |
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" | 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) |
?? |
bool | show_chr_env_collision | 0 | "draws character / environment collisions" (same as ph_show_collisions?) |
OK |
bool | show_flags | 0 | "enables the display of flags" (see BINA/OBJC/FLAG) |
?? |
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) |
?? |
bool | show_performance | 0 | "enables performance display" | 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) |
?? |
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 Rectangle is selected" (environment sounds, see BINA/OBJC/SNDG) |
?? |
bool | show_triggers | 0 | "enables the display of triggers" (see BINA/OBJC/TRIG) |
?? |
bool | show_turrets | 0 | "enables the display of turrets" (see BINA/OBJC/TURR) |
?? |
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" | OK |
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" | ?? |
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" | ?? |
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 |