OniGalore

BSL:Variables: Difference between revisions

BSL Discussion

BSL:Variables (view source)

Revision as of 02:54, 11 August 2024

2,798 bytes removed ,  11 August 2024
noted that wp_hypostrength definitely doesn't do anything
No edit summary
(noted that wp_hypostrength definitely doesn't do anything)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''Variables''' in BSL are very similar to variables in other programming languages. Here's a brief explanation of what a variable is:
To learn how to declare and use variables, read the BSL manual's [[BSL:Manual#Variables|Variables]] section. This page documents Oni's built-in (or "native") scripting variables. The other half of the available scripting commands are in [[BSL:Functions]].
 
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 [[BSL:Functions|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 [[BSL:Functions|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.
 
===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.


==Legend==
;Color
;Color
:White: available on all versions
:White: available in all versions
:Blue: command only exists in Mac Intel build
:Blue: command only exists in Mac Intel build
:Green: command only exists in Windows build
:Green: command only exists in Windows build
;Default value
;Default value
:'''# !!!''': reset by engine at level load
:'''[#] !!!''': reset to this number on level-load
:'''!?''': set by engine at game/level load, depends on [[persist.dat]]
:'''$ !!!''': set based on [[persist.dat]] at game/level-load
;Works
;Works
:"OK": both platforms can use this command
:"OK": both platforms can use this command
Line 57: Line 18:
:"NO": command is proven not to work
:"NO": command is proven not to work


==Built-in variables==
{|border=1 cellspacing=0 cellpadding=2
{|border=1 cellspacing=0 cellpadding=2
!Type!!Name!!Default value!!Comment!!Works
!Type!!Name!!Default value!!Comment!!Works
Line 191: Line 153:
|"makes the laser pointer hit all objects"<br>(determines whether the gun's aiming laser stops at quads marked with non-object-collision)||bgcolor=#ccccff|OK-M
|"makes the laser pointer hit all objects"<br>(determines whether the gun's aiming laser stops at quads marked with non-object-collision)||bgcolor=#ccccff|OK-M
|-
|-
|bool||[[am_invert]]||'''!?'''
|bool||[[am_invert]]||'''$ !!!'''
|"inverts aiming" This is set from [[persist.dat]] at game load (in the absence of '''persist.dat''' the default is 0).
|"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).
:The value 0 means normal aiming (mouse up to look up). The value 1 means inverted aiming (mouse down to look up). Unlike the backwards "Invert Mouse" checkbox on the Options screen (fixed in the [[AE]]), this variable does not work the opposite of how you would expect.
|OK
|OK
|-
|-
|bool||[[am_show_axes]]||0
|bool||[[am_show_axes]]||0
|"shows world axes"
|"shows world axes"
:This attaches a giant 3D axis to Konoko which claims to show the direction of positive x, y, and z in the world coordinate system, however it is '''wrong'''. Oni uses a Y-up coordinate system; do not let the 3D axis model showing Z-up mislead you.
:This attaches a giant 3D axis to Konoko which claims to show the direction of positive x, y, and z in the world coordinate system, however it is '''wrong'''. Oni uses a ''Y-up coordinate system''; do not let the world axis model showing Z-up mislead you.
|bgcolor=#ccccff|OK-M
|bgcolor=#ccccff|OK-M
|-
|-
Line 259: Line 221:
|-
|-
|bool||[[chr_debug_characters]]||0
|bool||[[chr_debug_characters]]||0
|"enables debugging information for characters"||OK
|"enables debugging information for characters"<br>(shows currently playing animation)||OK
|-
|-
|bool||[[chr_debug_collision]]||0
|bool||[[chr_debug_collision]]||0
Line 480: Line 442:
|"specifies the distance from the camera that flag names no longer draw"<br>(probably needs show_flags)||??
|"specifies the distance from the camera that flag names no longer draw"<br>(probably needs show_flags)||??
|-
|-
|int32||[[flag_new_id]]||'''!?'''
|int32||[[flag_new_id]]||'''$ !!!'''
|"specifies the id for a new flag"<br>(equal to the last flag added at level load)||??
|"specifies the id for a new flag"<br>(equal to the last flag added at level load)||??
|-
|-
Line 565: Line 527:
|-
|-
|bool||[[laser_alpha]]||0
|bool||[[laser_alpha]]||0
|WTF? lasers are always transparent||??
|WTF? lasers are always transparent (As I can see in SRC, this variable changes laser texture from '''non-transparent''' BGR555 <u>with</u> AdditiveBlend parameter to '''transparent''' ABGR4444 <u>without</u> AdditiveBlend.)||??
|-bgcolor="lime"
|-bgcolor="lime"
|bool||[[li_center_cursor]]||1
|bool||[[li_center_cursor]]||1
Line 645: Line 607:
|"factor" (for current ONWC; needs recoil_edit)||OK
|"factor" (for current ONWC; needs recoil_edit)||OK
|-
|-
|int32||[[save_point]]||'''!?'''
|int32||[[save_point]]||'''$ !!!'''
|which save point we are on||OK
|"which save point we are on"<br>(gets the current save point, which is set by Oni based on the player's choice of Save Point on the Load Game screen)||OK
|-
|-
|int32||[[saved_film_character_offset]]||1
|int32||[[saved_film_character_offset]]||1
Line 733: Line 695:
|-
|-
|bool||[[sync_debug]]||0
|bool||[[sync_debug]]||0
|"enables sync debugging"||??
|"enables sync debugging"<br>(prints a message to screen with how many frames were dropped during a cutscene; see function <tt>cutscene_sync</tt>)||NO
|-
|-
|float||[[target_max_distance]]||75000.
|float||[[target_max_distance]]||75000.
Line 766: Line 728:
|-
|-
|int32||[[wp_hypostrength]]||25
|int32||[[wp_hypostrength]]||25
|"sets strength of hypo spray"<br>apparently in % of full health, seems hard-coded||??
|"sets strength of hypo spray"<br>(development relic; changes variable which is unused)||NO
|-
|-
|bool||[[wp_kickable]]||0
|bool||[[wp_kickable]]||0
Line 779: Line 741:


[[Category:BSL docs]]
[[Category:BSL docs]]
[[Category:Scripting tasks]]
Retrieved from "https://wiki.oni2.net/Special:MobileDiff/29956...43187"