BSL:Variables: Difference between revisions
Jump to navigation
Jump to search
m (added introduction) |
(updated general notions) |
||
| Line 5: | Line 5: | ||
The usual thing to do in this situation is to store the needed data in a '''variable''': an elementary data container. | 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''. | |||
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" | The ''value'' or the variable is just the contents it currently stores. It can be read and written. | ||
==Declaration== | |||
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. | |||
==Assignment== | |||
Finally, the ''name'' of a variable is a unique text string that is used to identify the data container within the script. Like [[BSL:Functions|function]] names, variable names are case-sensitive (NOTE: [[BSL:Preset|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 [[BSL:Functions|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 [[BSL:Expressions|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== | ==Preset variables== | ||
;All the preset OSL variables are listed here, in alphabetical order. | ;All the preset OSL variables are listed here, in alphabetical order. | ||
| Line 70: | Line 104: | ||
|- | |- | ||
|bool||[[ai2_showactivationpaths]]||0 | |bool||[[ai2_showactivationpaths]]||0 | ||
|shows the initial pathfinding (upon | |shows the initial pathfinding (upon activation) of all AI||OK | ||
|- | |- | ||
|bool||[[ai2_showastar]]||0 | |bool||[[ai2_showastar]]||0 | ||
Revision as of 20:31, 13 July 2007
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 |