BSL:Variables

From OniGalore
Revision as of 20:31, 13 July 2007 by Geyser (talk | contribs) (updated general notions)
Jump to navigation Jump to 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: 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
Italic : reset by engine at level load (not checked yet for chr_buffer_size and beyond, unless specified)
Type Name Default value Comment Works
bool ai2_barabbas_run 1 all AI can apparently 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 ??
bool ai2_chump_stop 0 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 shows the initial pathfinding (upon activation) of all AI OK
bool ai2_showastar 0 shows something about the A* pathfinding ??
bool ai2_showcombatranges 0 shows near and far combat range of all AI OK
bool ai2_showconnections 0 shows the result of ai2_findconnections OK
bool ai2_showdynamicgrids 0 shows dynamic grids (moving obstacles) if ai2_showgrids is ON OK
bool ai2_showfights 0
bool ai2_showfiringspreads 0 shows the firing spread of all active weapons OK
bool ai2_showgrids 0 shows static grids (see AKVA) OK
bool ai2_showhealth 0 shows health and healthbar above every AI]] OK
bool ai2_showintersections 0
bool ai2_showjoblocations 0
bool ai2_showlasers 0 ??
bool ai2_showlinetochar 0 draws a line from the player to every char OK
bool ai2_showlocalmelee 0
bool ai2_showlos 0 the LOS of all aiming enemies leaves a permanent trace
bool ai2_shownames 0
bool ai2_showpathfindingerrors 0
bool ai2_showpaths 0
bool ai2_showprediction 0
bool ai2_showprojectiles 0
bool ai2_showsounds 0
bool ai2_showtargeting 0
bool ai2_showvision 0
int32 ai2_spacing_cookies 2
bool ai2_spacing_enable 1
bool ai2_spacingweights 1
int32 ai2_stopignoring_count 6 number of events before the AI will stop ignoring ??
int32 ai2_stopignoring_time 240 time before the AI forgets about ignored events, in frames ??
bool am_hit_everything 0 makes the laser pointer hit all objects ??
bool am_invert ?? inverts aiming OK
bool am_show_axes 0
bool am_show_closest 0
bool am_show_filenames 0 displays debug box
float character_name_distance 150. AFAIK, names are always drawn
bool chr_active 1 if OFF, all characters are inactive OK
float chr_aim_width 70. width of the aiming arc, in degrees OK
bool chr_all_active 0 forces offscreen characters to remain active OK
float chr_auto_aim_arc 90. width of the auto aiming arc, in degrees OK
float chr_auto_aim_dist 40. threshold distance for auto aiming, in world units OK
bool chr_big_head 0 enables custom head size factor for all characters OK
float chr_big_head_amount 4. custom head size factor for all characters OK
float chr_block_angle 20. width of the blocking angle, in degrees OK
int32 chr_buffer_size 8
bool chr_collision_box 1
float chr_collision_grow 0.
bool chr_corpse_fade_offscreen 1 makes characters fade to corpses when offscreen ??
int32 chr_death_fade_frames 180 time over which characters fade to corpses, in frames ??
int32 chr_death_fade_start 7200 time until characters fade to corpses, in frames ??
bool chr_debug_aiming_screen 0 enables dumping of aiming screen events to console OK
chr_debug_characters
chr_debug_collision
chr_debug_fall
chr_debug_footsteps
chr_debug_footsteps_verbose
chr_debug_handle
chr_debug_impacts
chr_debug_overlay
chr_debug_pathfinding
bool chr_debug_sphere 0 displays collision sphere(s) around characters
bool chr_debug_target 0
bool chr_debug_trigger_quad 0
bool chr_disable_melee 0 turns off all melee damage ??
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
chr_draw_facing_vector
chr_draw_weapon
bool chr_enable_collision 1 enables character collision OK
int32 chr_lod -1 character LOD (-1 = AUTO, 0 = xlow, ..., 4 = xhigh) OK
bool chr_mini_me 0 enables custom size factor for the main character OK
float chr_mini_me_amount 0.5 custom size factor for the main character OK
bool chr_pin_character 0 pins all characters (freezes coordinates) OK
chr_print_sound
chr_show_bnv
chr_show_lod
chr_show_movement
bool chr_weapon_auto_aim 1 enables auto aiming 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 in melee, 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 height to feet, in world units OK
int32 cm_jello_amt 20 percentage of wall transparency in Jello mode OK
float cm_jello_radius 12. radius of effect of Jello mode OK
float cm_lookspring_percent 0.5 percentage of lookspring at which fight mode turns off ??
bool cm_plane_test 1 enables plane test for Jello camera ??
co_display
co_fade_time
co_message_display
co_priority
debug_consoles
debug_font_cache
debug_gun_behavior
debug_impacts
debug_scripts
debug_triggers
debug_weapons
door_drawframes
bool door_ignore_locks 0 ignores locked state for all doors OK
door_pop_lighting
door_show_activation
door_show_debug
bool draw_every_frame 0 forces the drawing of every Nth frame OK
int32 draw_every_frame_multiple 1 sets the drawing frequency if draw_every_frame is ON OK
bool env_collision 1 enables environment collision ??
bool env_drawallgqs 0 ??
bool env_drawfrustum 0 ??
bool env_drawvisonly 0 ??
int32 env_highlight_gq -1 points out the quad with that ID (-1 means none) OK
int32 env_ray_number 20 number or rays cast per frame
bool env_show_ghostgqs 0 ??
bool env_show_leafnodes 0 ??
bool env_show_octnode_gqs 0
bool env_show_octtree 0
bool env_show_quad_count 0
bool env_show_rays 0
bool env_show_stairflagged 0
fast_lookup
fast_mode
flag_name_distance
flag_new_id
footstep_flash
fx_laser_width
bool gl_disable_depth_reads 0 disables depth reads ??
gl_disable_dxt1
gl_disable_packed_pixels
float gl_fog_blue 0.25 amount of blue fog (0 - 1) OK
float gl_fog_end 1. fog end OK
float gl_fog_green 0.25 amount of green fog (0 - 1) OK
float gl_fog_red 0.25 amount of red fog (0 - 1) OK
float gl_fog_start 0.975 fog start OK
gl_mipmap_offset
gs_input_accel
gs_screen_shot_reduce
gs_show_characters
bool gs_show_corpses 1 enables drawing of corpses OK
gs_show_environment
gs_show_object_count
gs_show_objects
gs_show_particles
gs_show_physics_count
gs_show_scripting_count
gs_show_shadows
gs_show_sky
bool gs_show_ui 1 enables Head-Up Display OK
gs_sleep
gs_stable_ear
bool invincible 0 makes player invincible OK
laser_alpha
li_center_cursor
m3_buffer_clear
m3_clear_color
m3_double_buffer
m3_fill_solid
m3_shade_vertex
m3_texture
m3_zcompareon
bool marketing_line_off 0 turns the laser sight off OK
ob_show_debug
bool omnipotent 0 makes player omnipotent OK
p3_debug_collision
p3_everything_breakable
p3_furniture_breakable
p3_glass_breakable
p3_show_env_collision
patrolpath_name_distance
ph_active
ph_debug_keyforces
ph_show_collisions
recoil_base
recoil_edit
recoil_factor
recoil_max
recoil_return_speed
int32 save_point ?? which save point we are on OK
int32 saved_film_character_offset 1
bool saved_film_loop 0 enables looping when play_recording OK
string sc_bind_f2 "" animation bound to cutscene1 OK
string sc_bind_f3 "" animation bound to cutscene2 OK
bool show_characters 1 toggles the display of characters OK
bool show_chr_env_collision 0 ??
bool show_flags 0 show flags? ??
bool show_laser_env_collision 0 ??
bool show_patrolpaths 0 ??
bool show_performance 0 OK
bool show_performance_gsd 0
bool show_performance_gsu 0
bool show_sound_all 0
bool show_sound_rectangles 0
bool show_sound_spheres 0
bool show_triggers 0
bool show_turrets 0
bool single_step 0 enables single step mode OK
float sky_height 0. Y offset of skybox? ??
bool sky_show_clouds 1 shows clouds? ??
bool sky_show_planet 1 shows planet(s) (sun in levels 2 and 3) OK
bool sky_show_sky 1 show sky (main switch) OK
bool sky_show_skybox 1 show skybox OK
bool sky_show_stars 1 show stars? (no stars in any level) ??
bool sound_show_debug 0 debugs sound channels OK
bool spatial_footsteps 1 OK
bool sync_debug 0
float target_max_distance 75000. distance to objective over which the radar arc changes size, in world units OK
bool turret_show_debug 0 no visible difference ??
bool ui_suppress_prompt 0 suppresses prompt about new objectives or moves 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 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 apparently in % of full health, seems hard-coded ??
bool wp_kickable 0 lets NPCs collide with weapons 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