Jump to content

BSL:Functions: Difference between revisions

BSL:Functions (view source)

Revision as of 15:24, 15 April 2023

1,120 bytes removed ,  15 April 2023
removed instructions on function usage, as this is covered better by BSL:Manual; rewrote legend and gave it its own section; added note on dump_docs
m (→‎ai2: added note to ai2_followme)
(removed instructions on function usage, as this is covered better by BSL:Manual; rewrote legend and gave it its own section; added note on dump_docs)
Line 1: Line 1:
{{TOCfloat}}
{{TOCfloat}}
==Signature==
To learn how to declare and use functions, read the BSL manual's [[BSL:Manual#Functions|Functions]] section. This page documents Oni's built-in (or "native") scripting functions. The other half of the available scripting commands are in [[BSL:Variables]].
===Arguments===
Put usage of brackets and commas here. Also tell about the weak syntax (with space as a separator).
===Return value===
When used alone forces the exit from a function. When used with a variable it forces the exit from a function and returns that variable.


Example (1)
==About chr_index==
 
<pre>
func void spawnUs () {
    ai2_spawn(Muro);
    sleep(200);
    return;
    ai2_spawn(Barabas);
}
</pre>
 
In this example the code <tt>ai2_spawn(Barabas);</tt> is never executed.
 
Example (2)
 
<pre>
var int current_char_id=0;
 
func int spawnCharacter (string char_name) {
    ai2_spawn(char_name);
    current_char_id=current_char_id+1;
    return current_char;
    dmsg("Hello.");
}
</pre>
 
In this example the current_char is returned from the function (notice the int declaration at the begin of function, which declares the type to return). <tt>dmsg("Hello.");</tt> is never executed.
 
==Declaration==
Put usage of <tt>func</tt> here.
: [...]
* Tips:
** If you call a second function from inside another function, the second function will be executed til its end and then the rest of the first function gets executed.
** You can call a function recursively, but only up to about four times, then the script execution stucks for some reason (maybe intentional to prevent endless loops?).
** BSL doesn't allow function name overriding even if the parameters are different (in java you can for example).
** Seems there is a limit of 8 parameters for each function.
{{clearall}}
==Multithreading==
Put usage of <tt>fork</tt> here.
: [...]
* Tips:
** Use "fork" in conjunction with "sleep" to ensure that there is always only one running copy of the function. (Themselves looping functions without sleep can crash the game.)
** And remember to design the code so it cannot create two copies of the function running in parallel. When that happens, the desired loop effect is usually broken and "echos" start to apprear.
==chr_index==
<tt>chr_index</tt> is a variable required by some functions like <tt>chr_focus</tt>. This variable hold a ID for a character and each character have a <tt>chr_index</tt> associated.
<tt>chr_index</tt> is a variable required by some functions like <tt>chr_focus</tt>. This variable hold a ID for a character and each character have a <tt>chr_index</tt> associated.


Line 78: Line 31:


If you want to reset <tt>chr_index</tt> you may want to use <tt>ai2_reset</tt>, which resets all characters to level initial state (take a look at <tt>ai2_reset</tt> implications before using it [[#ai2|here]]).
If you want to reset <tt>chr_index</tt> you may want to use <tt>ai2_reset</tt>, which resets all characters to level initial state (take a look at <tt>ai2_reset</tt> implications before using it [[#ai2|here]]).
 
{{clearall}}
==Native functions==
==Legend==
Line structure: script command [parameter] - description - example  
{{Fmbox
 
  | image = none
Parameter:
  | text = • function_name parameter_name:type - description - example<br>''Optional notes''
*parameter
}}
:you have to use this parameter
;Parameter
*parameter_name:type
:You have to supply this parameter.
*[parameter]
*[parameter]
:IMO, this parameter is an option. You can use it or not.
:This parameter is optional. You can use it or not.
*[parameter1:type1 | parameter2:type2]
:You can supply a parameter of the first type or second type.
*(null)
*(null)
:type only the script command, nothing else
:There are no parameters; you call the function by name alone.
*no parameter given
:type the script command and add "= 0" or "= 1" (sometimes you can add higher numbers, e.g. cm_distance = 200)


*<span style="color:green">Commands in this color are Windows-only</span>
;Description
*<span style="color:blue">Commands in this color are Mac-only</span>
The function name, parameters and description come directly from Oni (the command "dump_docs"). The description given after a dash is sometimes too short or cryptic to be of much use. Sometimes it's even a placeholder value like "bla bla bla" (thanks Bungie West). In those cases a modder may have added a note in italics under the function to explain what it really does.


;Availability
*<span style="color:green">Functions in this color are Windows-only</span>
*<span style="color:blue">Functions in this color are Mac-only</span>
==Native functions==
===ai2===
===ai2===
'''Commands which can have an effect on all AIs (see below to use these same commands on one AI):'''<br>
'''Commands which can have an effect on all AIs (see below to use these same commands on one AI):'''<br>
Line 274: Line 233:
*console_print - dumps all arguments
*console_print - dumps all arguments
*co_toggle_text - cycles console text color
*co_toggle_text - cycles console text color
*dump_docs - shows all registered variables and commands
*dump_docs - shows all registered variables and functions
''These will be dumped into the file script_commands.txt, next to Oni.''
*text_console name:string - turns on the text console display
*text_console name:string - turns on the text console display


Retrieved from "https://wiki.oni2.net/Special:MobileDiff/39696"