OniGalore

BSL:Functions: Difference between revisions

BSL Discussion

BSL:Functions (view source)

Revision as of 01:21, 16 June 2024

7,497 bytes added ,  16 June 2024
added key names for chr_holdkey
(→‎cinematic_: rewrite and move of flag illustration)
(added key names for chr_holdkey)
 
(48 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Signature==
{{TOCfloat}}
===Arguments===
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]].
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==
"chr_index" is a means of identifying a character in a level, required by some functions like <tt>chr_focus</tt>. Each character including the player-character has a chr_index associated with him/her. Typically the chr_index is determined by the spawn order of the characters. Characters can be spawned either by scripting or by the engine itself (if the character doesn't have the "NotInitiallyPresent" flag in the [[OBD:BINA/OBJC/CHAR|BINACJBOCharacter]] file).


<pre>
For example, if this was run after loading the level with no one spawned except Konoko…
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.
 
==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.
 
Normally the chr_index is associated by the order of the spawn of the characters. The characters can be spawned either by scripting or by the engine itself (if it doesn't have <tt>NotInitiallyPresent</tt> flag at <tt>BINACJBOCharacter</tt> file).
 
For example:
<pre>
<pre>
ai2_spawn Muro
ai2_spawn Muro
Line 60: Line 12:
</pre>
</pre>


With the follow code Muro will receive the index 1, Mukade index 2 and Bomber index 3. Konoko always have a <tt>chr_index</tt> of 0, because it's always the first character to be spawned.
…then Muro will receive chr_index 1, Mukade will have index 2 and the Bomber index 3. Konoko always has a chr_index of 0 because she's the first character to be spawned. As the game runs, however, things become more complicated. Once a character is deleted, either by being killed (after which the engine deletes them automatically) or by calling <tt>chr_delete</tt> directly, any characters spawned subsequently will fill in the holes left by the deleted characters.


This ok, but there's an exception. Once a character is deleted, either by <u>be killed</u> (and the engine delete it automatically) or by <u>calling <tt>chr_delete</tt></u> directly the following characters to be spawned will fill the holes left by the deleted.
For example, if this is done…
 
For example:
<pre>
<pre>
ai2_spawn Muro
ai2_spawn Muro
Line 72: Line 22:
</pre>
</pre>


In this example Mukade have the index 2, but once it's deleted (in this case directly by <tt>chr_delete</tt> function) there will be hole where his id were. When Bomber is spawned, it isn't associated the index 3, but it will be associated the index 2, to fill the hole left behind.
…Mukade will have index 2, but once he's deleted, his index will be freed up. When Bomber is spawned, he will receive index 2 in order to fill the hole left behind. If you are desperate to reset chr_index assignments for the sake of your scripting, you may want to use <tt>ai2_reset</tt>, which resets all characters to the level's initial state.
 
{{clearall}}
Seems the <tt>chr_index</tt> variables make part of an array in memory, once some variable in the array is cleared, in the next opportunity it is filled up again.
 
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 [http://wiki.oni2.net/BSL:Functions#ai2 here]).


==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.
 
===ai2_===
'''Commands which can have an effect on all AIs (see below to use these same commands on one AI):'''


;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===
'''Commands which can have an effect on all AIs (see below to use these same commands on one AI):'''<br>
*ai2_allpassive passive:int {0 | 1} - stops all AIs from thinking for themselves - ai2_allpassive 1
*ai2_allpassive passive:int {0 | 1} - stops all AIs from thinking for themselves - ai2_allpassive 1
*ai2_kill - kills one or more AIs
''If you don't specify any parameters to it, ai2_kill kills all AIs.''
*ai2_spawnall (null) - spawns all AI, even those not initially present - ai2_spawnall
*ai2_spawnall (null) - spawns all AI, even those not initially present - ai2_spawnall
*ai2_takecontrol on_off:int {0 | 1} - makes the AI movement system take control of the player - ai2_takecontrol 1
*ai2_takecontrol on_off:int {0 | 1} - makes the AI movement system take control of the player - ai2_takecontrol 1
*ai2_kill [int] - kills all AIs, just use a number as parameter instead of a string
*ai2_tripalarm - alarm_id:int [ai_name:string | script_id:int] - trips an alarm - ai2_tripalarm 2 0
''Tells all AIs about the character named in the third parameter (optional; default is the player-character). AIs will ignore the alarm if they are passive, are not set in their [[OBD:BINA/OBJC/CHAR|CHAR]] to respond to this alarm group, are an ally of the named character, or (when target is to be the player) they have had ai2_makeignoreplayer used on them or the variable ai2_ignore_player is true. The notified AIs will run to the target character's current location as of the time the alarm was tripped.''


'''Commands which have an effect on one AI:'''
'''Commands which have an effect on one AI:'''
Line 110: Line 65:
*ai2_debug_makesound [sound_type:string | ] [volume:float | ] - causes the player to make a sound (alerts nearby AIs)
*ai2_debug_makesound [sound_type:string | ] [volume:float | ] - causes the player to make a sound (alerts nearby AIs)
*ai2_doalarm [ai_name:string | script_id:int] [console_id:int] - tells an AI to run for an alarm - ai2_doalarm ambush_commguy_2 4
*ai2_doalarm [ai_name:string | script_id:int] [console_id:int] - tells an AI to run for an alarm - ai2_doalarm ambush_commguy_2 4
''if the AI is passive, ai2_doalarm cannot be executed''
''If the AI is passive, ai2_doalarm cannot be executed.''
*ai2_dopath [ai_name:string | script_id:int] path_name:string - tells an AI to run a particular path - ai2_dopath A_E3 patrol_49
*ai2_dopath [ai_name:string | script_id:int] path_name:string - tells an AI to run a particular path - ai2_dopath A_E3 patrol_49
''if the AI is passive, ai2_dopath cannot be executed''
''If the AI is passive, ai2_dopath cannot be executed.''
*ai2_findconnections [distance:int | ] - finds all BNV connections from the player's location
*ai2_findconnections [distance:int | ] - finds all BNV connections from the player's location
*ai2_followme [ai_name:string | script_id:int] - tells an AI to follow the player - ai2_followme s2_t05
*ai2_followme [ai_name:string | script_id:int] - tells an AI to follow the player - ai2_followme s2_t05
''The AI will navigate to your position, but will stay there instead of continuing to follow you.''
*ai2_forget [ai_name:string | script_id:int] [forget_char:string] - makes one or all AIs forget they saw anything - ai2_forget Sec_Ambush_BOL_1
*ai2_forget [ai_name:string | script_id:int] [forget_char:string] - makes one or all AIs forget they saw anything - ai2_forget Sec_Ambush_BOL_1
*ai2_idle [ai_name:string | script_id:int] - tells an AI to become idle - ai2_idle A1_intro01
*ai2_idle [ai_name:string | script_id:int] - tells an AI to become idle - ai2_idle A1_intro01
*ai2_inactive [ai_name:string | script_id:int] - forces an AI into inactive mode
*ai2_inactive [ai_name:string | script_id:int] - forces an AI into inactive mode
*ai2_kill [param1:string] [param2:string] - kills one or more AIs - ai2_kill ScanKerr01 // ai2_kill
*ai2_kill [param1:string] [param2:string] - kills one or more AIs - ai2_kill ScanKerr01
''You can kill every AI but one by specifying its name using the "except" keyword: <tt>ai2_kill except Griffin</tt>.''
*ai2_lookatchar [ai_name:string | script_id:int] [ai_name:string | script_id:int] - tells an AI to look at a character - ai2_lookatchar 0 Barabus
*ai2_lookatchar [ai_name:string | script_id:int] [ai_name:string | script_id:int] - tells an AI to look at a character - ai2_lookatchar 0 Barabus
''needs ai2_takecontrol 1 if Konoko should do that''
''Needs <tt>ai2_takecontrol 1</tt> if being used on Konoko.''
*ai2_lookatme [ai_name:string | script_id:int] - tells an AI to look at the player - ai2_lookatme s2_t05
*ai2_lookatme [ai_name:string | script_id:int] - tells an AI to look at the player - ai2_lookatme s2_t05
*ai2_makeaware [ai_name:string | script_id:int] [target_name:string | target_script_id:int] - makes an AI aware of another character - ai2_makeaware GrifElite04 char_0
*ai2_makeaware [ai_name:string | script_id:int] [target_name:string | target_script_id:int] - makes an AI aware of another character - ai2_makeaware GrifElite04 char_0
Line 127: Line 84:
*ai2_makeignoreplayer [ai_name:string | script_id:int] on_off:int{0 | 1} - makes a single AI ignore the player - ai2_makeignoreplayer ParkStriker 1
*ai2_makeignoreplayer [ai_name:string | script_id:int] on_off:int{0 | 1} - makes a single AI ignore the player - ai2_makeignoreplayer ParkStriker 1
*ai2_movetoflag [ai_name:string | script_id:int] flag_id:int [setfacing:string{"setfacing"}] - tells an AI to move to a flag - ai2_movetoflag 0 1091
*ai2_movetoflag [ai_name:string | script_id:int] flag_id:int [setfacing:string{"setfacing"}] - tells an AI to move to a flag - ai2_movetoflag 0 1091
''needs ai2_takecontrol 1 if Konoko should do that''<br />
''ai2_movetoflag will only work if there is a path to that flag. Needs <tt>ai2_takecontrol 1</tt> if being used on Konoko.''
''ai2_movetoflag will only work if there is a path to that flag''
*ai2_neutralbehavior [ai_name:string | script_id:int] behavior:string - sets up an AI's neutral-interaction - ai2_neutralbehavior neutral_3 none
*ai2_neutralbehavior [ai_name:string | script_id:int] behavior:string - sets up an AI's neutral-interaction - ai2_neutralbehavior neutral_3 none
*ai2_noncombatant [ai_name:string | script_id:int] non_combatant:int{0 | 1} - sets or clears an AI's non-combatant state - ai2_noncombatant A1_intro01 1
*ai2_noncombatant [ai_name:string | script_id:int] non_combatant:int{0 | 1} - sets or clears an AI's non-combatant state - ai2_noncombatant A1_intro01 1
Line 138: Line 94:
*ai2_report_verbose [ai_name:string | script_id:int | ] - tells an AI to report in verbosely
*ai2_report_verbose [ai_name:string | script_id:int | ] - tells an AI to report in verbosely
*ai2_reset [reset_player:int] - resets AI as if start of level - ai2_reset
*ai2_reset [reset_player:int] - resets AI as if start of level - ai2_reset
''resets consoles and clears characters as if you started the level again''
''Resets all consoles and characters as if you started the level again.''
*ai2_set_handlesilenterror handle_silent:bool [subsystem:string | ] - sets whether handled errors are silent
*ai2_set_handlesilenterror handle_silent:bool [subsystem:string | ] - sets whether handled errors are silent
*ai2_set_logerror error_level:string [subsystem:string | ] - sets the level of errors to log to file
*ai2_set_logerror error_level:string [subsystem:string | ] - sets the level of errors to log to file
Line 144: Line 100:
*ai2_setalert [ai_name:string | script_id:int] alert:string - sets the alert state of an AI - ai2_setalert Floor2_Striker_2 high (alert strings: lull, low, medium, high, combat)
*ai2_setalert [ai_name:string | script_id:int] alert:string - sets the alert state of an AI - ai2_setalert Floor2_Striker_2 high (alert strings: lull, low, medium, high, combat)
*ai2_setjobstate [ai_name:string | script_id:int] - tells an AI to take its current state as its job - ai2_setjobstate E_Er34
*ai2_setjobstate [ai_name:string | script_id:int] - tells an AI to take its current state as its job - ai2_setjobstate E_Er34
''if the AI is passive, ai2_setjobstate cannot be executed''
''If the AI is passive, ai2_setjobstate cannot be executed.''
*ai2_setmovementmode [ai_name:string | script_id:int] mode:string - sets an AI's current movement mode - ai2_setmovementmode finalam_striker_1 walk  (movement mode strings: creep, walk, walk_noaim, run, run_noaim)
*ai2_setmovementmode [ai_name:string | script_id:int] mode:string - sets an AI's current movement mode - ai2_setmovementmode finalam_striker_1 walk  (movement mode strings: creep, walk, walk_noaim, run, run_noaim)
''needs ai2_takecontrol 1 if Konoko should do that''
''Needs <tt>ai2_takecontrol 1</tt> if being used on Konoko.''
*ai2_showmem - shows AI memory usage
*ai2_showmem - shows AI memory usage
*ai2_skill_bestangle best_angle:float - sets an AI's best aiming angle in degrees
*ai2_skill_bestangle best_angle:float - sets an AI's best aiming angle in degrees
Line 152: Line 108:
*ai2_skill_delaymax maxdelay:int - sets an AI's max delay between shots, in frames
*ai2_skill_delaymax maxdelay:int - sets an AI's max delay between shots, in frames
*ai2_skill_delaymin mindelay:int - sets an AI's min delay between shots, in frames
*ai2_skill_delaymin mindelay:int - sets an AI's min delay between shots, in frames
*ai2_skill_error error_amount:float - sets an AI's grouping error
*ai2_skill_error error_amount:float - sets an AI's grouping error (demonstration [https://www.youtube.com/watch?v=cxTz30YOPhc HERE])
*ai2_skill_inaccuracy inaccuracy:float - sets an AI's shooting inaccuracy multiplier
*ai2_skill_inaccuracy inaccuracy:float - sets an AI's shooting inaccuracy multiplier
*ai2_skill_recoil recoil_compensation:float - sets an AI's recoil compensation amount (0-1)
*ai2_skill_recoil recoil_compensation:float - sets an AI's recoil compensation amount (0-1)
Line 160: Line 116:
*ai2_skill_show - shows the currently selected shooting skill
*ai2_skill_show - shows the currently selected shooting skill
*ai2_spawn ai_name:string [force_spawn:string{"force"}] - creates and starts an AI from a character object - ai2_spawn ambush_striker_2
*ai2_spawn ai_name:string [force_spawn:string{"force"}] - creates and starts an AI from a character object - ai2_spawn ambush_striker_2
*ai2_tripalarm - alarm_id:int [ai_name:string | script_id:int] - trips an alarm - ai2_tripalarm 2 0


===chr_===
===chr===
'''Commands which have an effect on all characters:'''
'''Commands which have an effect on all characters:'''


Line 170: Line 125:


*chr_animate [ai_name:string | script_id:int] anim_name:string [num_frames:int] [interp_frames:int] - plays an animation on a character - chr_animate 0 KONOKOcycle_ride 500
*chr_animate [ai_name:string | script_id:int] anim_name:string [num_frames:int] [interp_frames:int] - plays an animation on a character - chr_animate 0 KONOKOcycle_ride 500
''If you specify num_frames, and the number is longer than the animation, it will loop continuously until num_frames is satisfied.''
*chr_animate_block [ai_name:string | script_id:int] anim_name:string [num_frames:int] [interp_frames:int] - plays an animation on a character and blocks until done - chr_animate_block 0 KONOKOlev11_cnsl_idle 300
*chr_animate_block [ai_name:string | script_id:int] anim_name:string [num_frames:int] [interp_frames:int] - plays an animation on a character and blocks until done - chr_animate_block 0 KONOKOlev11_cnsl_idle 300
*chr_boss_shield [ai_name:string | script_id:int] - turns on the boss shield for a character - chr_boss_shield OutroNinja
*chr_boss_shield [ai_name:string | script_id:int] - turns on the boss shield for a character - chr_boss_shield OutroNinja
''See [[Shields]] for a definition of "boss shield".''
*chr_changeteam [ai_name:string | script_id:int] team_name:string - changes a character's team - chr_changeteam guard1 Syndicate
*chr_changeteam [ai_name:string | script_id:int] team_name:string - changes a character's team - chr_changeteam guard1 Syndicate
''team name strings: Konoko, TCTF, Syndicate, Neutral, SecurityGuard, RogueKonoko, Switzerland, SyndicateAccessory''
''Team name strings: Konoko, TCTF, Syndicate, Neutral, SecurityGuard, RogueKonoko, Switzerland, SyndicateAccessory''
*chr_create script_id:int [start_create:string {"start"} | ] - creates a character from an ID of the AISA file - chr_create 1050 start
*chr_create script_id:int [start_create:string {"start"} | ] - creates a character from an ID of the AISA file - chr_create 1050 start
*chr_death_lock [ai_name:string | script_id:int] [on_off:int{0 | 1}] - this character will not die too much - chr_death_lock dum_hit_flash 1
*chr_death_lock [ai_name:string | script_id:int] [on_off:int{0 | 1}] - this character will not die too much - chr_death_lock dum_hit_flash 1
Line 193: Line 150:
''powerup strings: ammo, cell, hypo, shield (in percent), invis (invisibility in frames, -1 = forever), lsi (amount is ignored)''
''powerup strings: ammo, cell, hypo, shield (in percent), invis (invisibility in frames, -1 = forever), lsi (amount is ignored)''
*chr_giveweapon [ai_name:string | script_id:int] weapon_name:string - gives a character a new weapon - chr_giveweapon 0 w1_tap
*chr_giveweapon [ai_name:string | script_id:int] weapon_name:string - gives a character a new weapon - chr_giveweapon 0 w1_tap
''weapon strings: w1_tap, w2_sap, w3_phr, w4_psm, w5_sbg, w6_vdg, w7_scc, w8_mbo, w9_scr, w10_sni, w11_ba1, w12_ba2''
''weapon names: w1_tap, w2_sap, w3_phr, w4_psm, w5_sbg, w6_vdg, w7_scc, w8_mbo, w9_scr, w10_sni, w11_ba1, w12_ba2''
*chr_has_empty_weapon [ai_name:string | script_id:int] - returns if this character is holding a weapon that is empty - chr_has_empty_weapon(char_0)
*chr_has_empty_weapon [ai_name:string | script_id:int] - returns if this character is holding a weapon that is empty - chr_has_empty_weapon(char_0)
''This function only returns if the player is out of ammo for the weapon and the weapon is also empty.''
''This function only returns if the player is out of ammo for the weapon and the weapon is also empty.''
Line 199: Line 156:
*chr_health chr_index:int [hit_points:int] - sets character's health  - chr_health 0 300
*chr_health chr_index:int [hit_points:int] - sets character's health  - chr_health 0 300
*chr_holdkey [ai_name:string | script_id:int] key_name:string num_frames:int - forces a character to hold a key down for some frames
*chr_holdkey [ai_name:string | script_id:int] key_name:string num_frames:int - forces a character to hold a key down for some frames
''key names: forward, back, stepleft, stepright, turnleft, turnright, crouch, jump, fire, altfire, punch, kick, action''
*chr_inv_reset [ai_name:string | script_id:int] - clears a characters inventory - chr_inv_reset ambush_tanker_1a
*chr_inv_reset [ai_name:string | script_id:int] - clears a characters inventory - chr_inv_reset ambush_tanker_1a
*chr_invincible [ai_name:string | script_id:int] [on_off:int{0 | 1}] - makes a character invincible - chr_invincible char_0 1
*chr_invincible [ai_name:string | script_id:int] [on_off:int{0 | 1}] - makes a character invincible - chr_invincible char_0 1
Line 207: Line 165:
*chr_lock_active [ai_name:string | script_id:int] - locks the character active - chr_lock_active IntroMuro
*chr_lock_active [ai_name:string | script_id:int] - locks the character active - chr_lock_active IntroMuro
*chr_main_class [class_name:string | class_index:int] - sets the main characters class - chr_main_class striker_easy_1
*chr_main_class [class_name:string | class_index:int] - sets the main characters class - chr_main_class striker_easy_1
''This seems to be different from chr_set_class (besides the parameters). For example with chr_main_class(ninja_hard_1) your ninja will be right handed while with chr_set_class(0,ninja_hard_1) your ninja will be left handed.''
''If you provide an index number ("IN") higher than the available number of characters ("NC"), the engine will keep iterating through the available characters, wrapping around when it hits the end, until it has traversed IN characters. For instance if NC = 85 and you input chr_main_class(180), the engine will change your class to the index 10 (180-85-85).''
 
''The practical effect seems to be different than chr_set_class (besides the parameters). For example with chr_main_class(ninja_hard_1) your ninja will be righthanded while with chr_set_class(0,ninja_hard_1) your ninja will be lefthanded. Another difference is that chr_main_class seem to disable the Daodan effect when using chr_super on the character itself.''
*chr_neutral [ai_name:string | script_id:int] passive:int{0 | 1} - stops an AI from thinking for itself - chr_neutral ParkStriker 1
*chr_neutral [ai_name:string | script_id:int] passive:int{0 | 1} - stops an AI from thinking for itself - chr_neutral ParkStriker 1
*chr_nocollision [ai_name:string | script_id:int] on_off:int{0 | 1} - disables collision for a character - chr_nocollision 0 1
*chr_nocollision [ai_name:string | script_id:int] on_off:int{0 | 1} - disables collision for a character - chr_nocollision 0 1
Line 214: Line 174:
''Normally used in cutscenes so the player leaves the fighting pose.''
''Normally used in cutscenes so the player leaves the fighting pose.''
*chr_playback [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film
*chr_playback [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film
''See comments on this function where it occurs under the [[#film|film section]].''
*chr_playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete
*chr_playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete
*chr_playback_debug film_name:string - dumps stats for a playback film
*chr_playback_debug film_name:string - dumps stats for a playback film
*chr_poison [ai_name:string | script_id:int] damage:int interval:int [initial_interval:int] - slowly poisons a character - chr_poison (konoko, 10, 60, 90);
*chr_poison [ai_name:string | script_id:int] damage:int interval:int [initial_interval:int] - slowly poisons a character - chr_poison (konoko, 10, 60, 90);
''This is intended to be called repeatedly by a trigger volume for a character standing in an area that does continual damage, such as a fire; thus, calling the function once directly from a script will have no effect.''
''This is intended to be called in a continuous stream for a character standing in a trigger volume which represents an area that does ambient damage, such as a fire. No damage is done for the first "initial_interval" frames that the function is called, or, when "initial_interval" is not supplied, for the first "interval" frames; and then additional damage is only done once every "interval" frames as the function continues to be called every frame by the TV. Thus, calling this function a single time directly from a script will have zero effect.''
*chr_set_class chr_index:int [class_name:string | class_index:int] - sets the character class of a specific character, class must exist otherwise the game crashes - chr_set_class 0 striker_easy_1
*chr_set_class chr_index:int [class_name:string | class_index:int] - sets the character class of a specific character, class must exist otherwise the game crashes - chr_set_class 0 striker_easy_1
*chr_set_health [ai_name:string | script_id:int] hit_points:int - sets a characters health by script id - chr_set_health dum_hit_flash 50
*chr_set_health [ai_name:string | script_id:int] hit_points:int - sets a characters health by script id - chr_set_health dum_hit_flash 50
Line 224: Line 185:
''chr_showextent_globals must be on for this to work.''
''chr_showextent_globals must be on for this to work.''
*<span style="color:blue">chr_showextent_globals - shows the global parts of an attack animation's extent - chr_showextent 1</span>
*<span style="color:blue">chr_showextent_globals - shows the global parts of an attack animation's extent - chr_showextent 1</span>
*chr_super [ai_name:string | script_id:int] super_amount:float - set's a character's super value - chr_super 0 1
*chr_super [ai_name:string | script_id:int] super_amount:float - set's a character's super value
''This sets a character's "<u>external</u> super" value, meaning their Daodan glow, but will not grant them any special powers such as Daodan overpower. It is used to give Konoko her Daodan glow in the Mountain Compound opening cutscene (she isn't granted overhealth until the cutscene ends). The super_amount value determines the brightness of the Daodan particles: consider the effective range to be 1-10. The Compound cutscene gives Konoko a glow of 1, and the cheat code "chenille" gives her a glow of 10.''
*chr_talk [ai_name:string | script_id:int] sound_name:string pre_pause:int post_pause:int [priority:string | ] - causes a character to play a line of dialogue - chr_talk victim_mansci_1 c02_62_11sci 0 0
*chr_talk [ai_name:string | script_id:int] sound_name:string pre_pause:int post_pause:int [priority:string | ] - causes a character to play a line of dialogue - chr_talk victim_mansci_1 c02_62_11sci 0 0
*chr_teleport [ai_name:string | script_id:int] flag_id:int - teleports a character to a flag - chr_teleport 0 105
*chr_teleport [ai_name:string | script_id:int] flag_id:int - teleports a character to a flag - chr_teleport 0 105
Line 231: Line 193:
*chr_unlock_active [ai_name:string | script_id:int] - unlocks the character active
*chr_unlock_active [ai_name:string | script_id:int] - unlocks the character active
*chr_unstoppable [ai_name:string | script_id:int] [on_off:int{0 | 1}] - makes a character unstoppable - chr_unstoppable IntroMuro 1
*chr_unstoppable [ai_name:string | script_id:int] [on_off:int{0 | 1}] - makes a character unstoppable - chr_unstoppable IntroMuro 1
*chr_vocalize [ai_name:string | script_id:int] type:string - makes a character utter a vocalization (vocalize type strings: override, yell, pain, call, say, chatter, idle)
*chr_vocalize [ai_name:string | script_id:int] type:string - makes a character utter a vocalization (vocalize type strings: taunt, alert, startle, checkbody, pursue, cower, superpunch, superkick, super3, super4). Character must be present in AISA file in order to work. Otherwise it will vocalize only the player.
*chr_wait_animation [ai_name:string | script_id:int] [anim_name:string]  - waits for a character to play a specific animation - chr_wait_animation 0 KONSPRrun_lt KONSPRrun_rt
*chr_wait_animation [ai_name:string | script_id:int] [anim_name:string]  - waits for a character to play a specific animation - chr_wait_animation 0 KONSPRrun_lt KONSPRrun_rt
*chr_wait_animstate [ai_name:string | script_id:int] [anim_name:string] - waits for a character to reach a specific animation state - chr_wait_animstate 0 run_slide
*chr_wait_animstate [ai_name:string | script_id:int] [anim_name:string] - waits for a character to reach a specific animation state - chr_wait_animstate 0 run_slide
*chr_wait_animtype [ai_name:string | script_id:int] [anim_name:string] - waits for a character to play a specific animation type - chr_wait_animtype 0 jump
*chr_wait_animtype [ai_name:string | script_id:int] [anim_name:string] - waits for a character to play a specific animation type - chr_wait_animtype 0 jump
*chr_wait_health [ai_name:string | script_id:int] health_amount:float - waits until a character's health falls below a value - chr_wait_health Muro 200
*chr_wait_health [ai_name:string | script_id:int] health_amount:int32 - waits until a character's health falls below a value - chr_wait_health Muro 200
*chr_weapon chr_index:int [weapon_name:string | weapon_num:int] - sets the weapon for a give character
*chr_weapon chr_index:int [weapon_name:string | weapon_num:int] - sets the weapon for a give character
*chr_weapon_immune [ai_name:string | script_id:int] - makes a character weapon immune - chr_weapon_immune(vat_bot_1); // chr_weapon_immune 0
*chr_weapon_immune [ai_name:string | script_id:int] - makes a character weapon immune - chr_weapon_immune(vat_bot_1); // chr_weapon_immune 0
Line 267: Line 229:
*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


Line 281: Line 244:


===cutscene===
===cutscene===
*begin_cutscene (null) - begins a cutscene - begin_cutscene
*begin_cutscene flag:string{"weapon" | "jello" | "ai" | "invis" | "nosync" | "keepparticles" | "animation" | "nojump"} - begins a cutscene - begin_cutscene
''begin_cutscene weapon - player does not holster his weapon when cutscene starts''<br />
''<tt>begin_cutscene</tt> will take as many arguments as you care to pass it, although BWest only ever passed it "jello", "weapon", or no argument at all. Each argument is a thing that you want to <u>retain</u> for the cutscene, otherwise it will be turned off:''<br>
''what about ai, animation, invis, jello, keepparticles, nojump, nosync?''
''"weapon": The player's weapon will not be holstered as the cutscene starts.''<br>
*cutscene_sync (null) - marks a point in a cutscene - cutscene_sync on
''"jello": Do not turn off [[jello-cam]].''<br>
''"ai": Do not turn off the AI (normally <tt>begin_cutscene</tt> internally performs <tt>ai2_allpassive 1</tt>).''<br>
''"invis": Do not remove the player's phase cloak.''<br>
''"nosync": Do not engage cutscene syncing (see <tt>cutscene_sync</tt>).''<br>
''"keepparticles": Don't delete dangerous particles that are currently active.''<br>
''"animation": Don't force the character to stand still.''<br>
''"nojump": Don't zero the character's lateral velocity if they are mid-jump.''<br>
*cutscene_sync state:string{"mark" | "on" | "off"} - marks a point in a cutscene - cutscene_sync on
''Cutscene syncing prevents audio from getting out of time with the visuals when the game is dropping frames during a cutscene, keeping the game world in time with the system clock instead of letting the game slow down. At one time, BWest was calling <tt>cutscene_sync on</tt> at the start of a cutscene to enable syncing. They would then mark a point at which audio must be synced with the visuals using <tt>cutscene_sync</tt> or <tt>cutscene_sync mark</tt>. However "mark" no longer does anything, as a mark is made whenever this function is called. More importantly, calling <tt>begin_cutscene</tt> automatically engages cutscene sync unless you specifically request it not to, making this function generally obsolete.''
*end_cutscene (null) - ends a cutscene - end_cutscene
*end_cutscene (null) - ends a cutscene - end_cutscene
*fade_in ticks:int - fades the screen in - fade_in 120
*fade_in ticks:int - fades the screen in - fade_in 120
Line 291: Line 262:
*letterbox start_stop:int{0 | 1} - starts or stops letterboxing - letterbox 0
*letterbox start_stop:int{0 | 1} - starts or stops letterboxing - letterbox 0


===diary_===
===diary===
*diary_page_unlock page:int - unlocks a specific diary page on the current level
*diary_page_unlock page:int - unlocks a specific diary page on the current level


===door_===
===door===
*door_open door_id:int - opens a door (may not stay open) - door_open 21
*door_open door_id:int - opens a door (may not stay open) - door_open 21
*door_close door_id:int - closes a door (may not stay open) - door_close 27
*door_close door_id:int - closes a door (may not stay open) - door_close 27
Line 302: Line 273:
*door_unjam door_id:int - unjams a door so characters can open it - door_unjam 8
*door_unjam door_id:int - unjams a door so characters can open it - door_unjam 8


===env_===
===env===
*debug_env_anim name:string - draws a line for an environment animation
*debug_env_anim name:string - draws a line for an environment animation
*env_anim obj_id:int [ obj_id:int] - initiates an environment animation for an object - env_anim 901 906
*env_anim obj_id:int [ obj_id:int] - initiates an environment animation for an object - env_anim 901 906
Line 316: Line 287:
===film===
===film===
*chr_playback [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film
*chr_playback [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film
''Film playback has three modes: normal (default), fromhere and interp. When you ask for a film to play without specifying a mode, e.g. <tt>playback 0 IntroKonokoAim</tt> it warps the character to an XYZ starting location contained in the [[FILM]]. If you instead write <tt>playback 0 IntroKonokoAim '''fromhere'''</tt>, it ignores the starting location and plays the film from the character's current location. You can interpolate from the character's current position to the film's starting position with <tt>playback 0 IntroKonokoAim '''interp 20'''</tt> to avoid a small jump in location (however this will be rejected if the distance is greater than 80 world units). After "interp" comes the number of frames to which this interpolation should be applied as the film starts playing.''
*chr_playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete
*chr_playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete
*chr_playback_debug film_name:string - dumps stats for a playback film
*chr_playback_debug film_name:string - dumps stats for a playback film
Line 321: Line 293:
*playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete - playback_block Start_Friend_1 roll fromhere // playback_block hangar1f_enemy_2 bomber_jump interp 30
*playback_block [ai_name:string | script_id:int] film_name:string [mode:string{"fromhere" | "interp"}] [num_frames:int] - plays back a film and blocks until complete - playback_block Start_Friend_1 roll fromhere // playback_block hangar1f_enemy_2 bomber_jump interp 30
*playback_debug film_name:string - dumps stats for a playback film
*playback_debug film_name:string - dumps stats for a playback film
''The above three functions are simply aliases for chr_playback*.''
*sc_focus chr_index:int - sets which character we're authoring for a film
*sc_focus chr_index:int - sets which character we're authoring for a film


Line 330: Line 303:
*did_kill_griffen (null) - returns if we did kill griffen - did_kill_griffen()
*did_kill_griffen (null) - returns if we did kill griffen - did_kill_griffen()
*difficulty (null) - returns the difficulty level
*difficulty (null) - returns the difficulty level
''See [[Difficulty modes]] for all the factors changed with the difficulty level.''
*flag_view_prefix prefix:string - view flags with a specific prefix
*flag_view_prefix prefix:string - view flags with a specific prefix
*hang when:string{"now"} - hangs the game (used for testing error handling)
*hang when:string{"now"} - hangs the game (used for testing error handling)
Line 336: Line 310:
*perf_prefix - sets the perf prefix
*perf_prefix - sets the perf prefix
*ph_status - xxx
*ph_status - xxx
''the "ph" is for physics''
''lists the physics status (collision type) of objects (characters, weapons, doors, etc.) that are currently in use''
*print_state state:int - prints an anim state
*print_state state:int - prints an anim state
*print_type type:int - prints an anim type  
*print_type type:int - prints an anim type  
*restore_game (null) - restores the game - restore_game
*restore_game (null) - restores the game - restore_game
''Tells the game to load from disk the player state data saved in [[persist.dat]] – Konoko's position, health and inventory – for the current save point. The save point can be set in two ways: the player selecting an option from the Load Game screen, and the <tt>save_game</tt> function being called.''
*save_game save_point:int [type:string{"autosave"}] - saves the game - save_game 1 autosave
*save_game save_point:int [type:string{"autosave"}] - saves the game - save_game 1 autosave
''Saves the player state to persist.dat. <tt>save_point</tt> is restricted to the range 0-10, but only values 1-10 are expected to be passed in. If you pass in "0", the error "invalid save point" will print on the console line but Oni will actually create "Save Point 0" under that level (or "Save Point -1" in the case of Chapter 1!). Loading this save point will be equivalent to clicking on the level title.<br>The only effect of passing "autosave" as the third parameter is playing the game-saved sound effect and displaying the message "Game saved." The game will be saved with or without it. No other value for this parameter has special meaning.''
*splash_screen texture:string - displays a splash screen - splash_screen warehouse_splash_screen
*splash_screen texture:string - displays a splash screen - splash_screen warehouse_splash_screen
*tr_stop_lookup - bla bla bla
*tr_stop_lookup - bla bla bla
*tr_write_animation anim_name:string file_name:string - bla bla bla
*tr_write_animation anim_name:string file_name:string - varient values  are output as hex
*tr_write_collection collection_name:string file_name:string - bla bla bla
*tr_write_collection collection_name:string file_name:string - bla bla bla
*tr_write_lookup file_name:string - bla bla bla
*tr_write_lookup file_name:string - bla bla bla
Line 363: Line 339:
*bind input_name:string to:string{"to"} input_function:string - binds an input to a function - bind numpad0 to forward
*bind input_name:string to:string{"to"} input_function:string - binds an input to a function - bind numpad0 to forward
*lock_keys [key_name:string] - locks keys out - lock_keys keys_walk ''key name strings: keys_reload, keys_hypo, keys_walk, keys_inventory, keys_action, keys_pause, keys_attack, keys_crouch, keys_jump, keys_movement''
*lock_keys [key_name:string] - locks keys out - lock_keys keys_walk ''key name strings: keys_reload, keys_hypo, keys_walk, keys_inventory, keys_action, keys_pause, keys_attack, keys_crouch, keys_jump, keys_movement''
''The lock_keys command allows you to enable or disable player keys. Using only lock_keys without a parameter will lock all keys. To unlock a specific set of keys you use the additional parameter, e.g. lock_keys keys_movement will unlock the move keys.''
*unbind input_name:string - removes a binding from a input function - unbind numpad0
*unbind input_name:string - removes a binding from a input function - unbind numpad0
*unbindall (null) - removes all bindings - unbindall
*unbindall (null) - removes all bindings - unbindall
Line 368: Line 345:
===message===
===message===
*dmsg astring:string - debugging message - dmsg [b. hello]
*dmsg astring:string - debugging message - dmsg [b. hello]
''[b. hello] ==> b stands for blue, it's the colour of the word hello [.hello] ==> without a character in front of the point, the colour of the word is white. Available colours: b (blue), c (cyan), g (green), l (lila), o (orange), r (red), u (umber), y (yellow)''
''dmsg prints to the subtitle area; the "b" in [b. hello] stands for "blue", setting the color of the word "hello". Available colors: b (blue), c (cyan), g (green), l (lavender), o (orange), r (red), u (umber), y (yellow)''
*dprint astring:string - debugging print
*dprint astring:string - debugging print
''dprint prints to the console output. Note that calling dprint and dmsg more than once within a single function produces unexpected results; two calls result in one of the dprint/dmsg calls becoming the return value for the function (even if it it's type "void") or sometimes creating a return value of 0, and more than two calls might be ignored.''
*message message:string [timer:int] - sends a message from the subtitle file - message begin_fight 240
*message message:string [timer:int] - sends a message from the subtitle file - message begin_fight 240
*message_remove [message:string] - removes a currently displayed message - message_remove c01_50_23 // message_remove
*message_remove [message:string] - removes a currently displayed message - message_remove c01_50_23 // message_remove


===movie===
===movie===
*movie_play name:string - function to start a movie playing
*<span style="color:green">movie_play name:string - function to start a movie playing</span>


===object===
===object===
Line 392: Line 370:
*p3_count - lists a count of P3 particles
*p3_count - lists a count of P3 particles
*p3_daodan_disable - disables parts of the daodan shield (for debugging)
*p3_daodan_disable - disables parts of the daodan shield (for debugging)
*p3_dumpparticles - jump all particles to a text file
*p3_dumpparticles - dump all particles to a text file
*p3_killall - kills all P3 particles
*p3_killall - kills all P3 particles
*p3_killnearest - kills the nearest P3 particle
*p3_killnearest - kills the nearest P3 particle
*p3_printtags - prints out all environmental particles with tags
*p3_printtags - prints out all environmental particles with tags
*p3_removedangerous (null) - removes all "dangerous projectile" particles by making their lifetime expire - p3_removedangerous
*p3_removedangerous (null) - removes all "dangerous projectile" particles by making their lifetime expire (example mukade energy balls) - p3_removedangerous
*p3_spawn particle_class:string [velocity:float | ] - spawns a new P3 particle
*p3_spawn particle_class:string [velocity:float | ] - spawns a new P3 particle
*p3_startall - creates and starts all environmental particles
*p3_startall - creates and starts all environmental particles
Line 446: Line 424:
*sound_ambient_stop name:string - function to stop an ambient sound - sound_ambient_stop alarm_loop
*sound_ambient_stop name:string - function to stop an ambient sound - sound_ambient_stop alarm_loop
*sound_ambient_volume name:string [volume:float] [time:float] - function to set the volume of a playing ambient sound - sound_ambient_volume alarm_loop .35 1.0
*sound_ambient_volume name:string [volume:float] [time:float] - function to set the volume of a playing ambient sound - sound_ambient_volume alarm_loop .35 1.0
''"Dialogue" is routinely misspelled as "dialog" in the following command names and descriptions.''
*sound_dialog_play name:string - function to start character dialog playing - sound_dialog_play c00_01_18shinatama
*sound_dialog_play name:string - function to start character dialog playing - sound_dialog_play c00_01_18shinatama
*sound_dialog_play_block name:string - function to start character dialog playing after the current dialog finishes - sound_dialog_play_block c00_01_67shinatama
*sound_dialog_play_block name:string - function to start character dialog playing after the current dialog finishes - sound_dialog_play_block c00_01_67shinatama
''Making two successive calls to sound_dialog_play will cause the second line of dialogue to fail to play, and you will only hear the first line. In the level scripts, BWest prevents this by either (1) using sleep() between them, (2) calling another function that blocks further script execution for a while such as chr_animate_block or cm_anim_block, or (3) using sound_dialog_play_block. This function is commonly called with either no argument or the argument "pause", which has no meaning to the function; "pause" was either a mnemonic for the developers indicating the purpose of the function call or else the function was changed during development. The only argument that has meaning to sound_dialog_play_block is the name of a sound. However, even when no valid sound name is received to be played by the function, it still has the effect of blocking on the currently playing dialogue. Thus you will commonly see "sound_dialog_play_block" or "sound_dialog_play_block pause" calls between occurrences of sound_dialog_play. More rarely, you will see calls of the format "sound_dialog_play_block ''actual_sound_name''" for the next line of dialogue, which is more efficient than making an empty call to sound_dialog_play_block between sound_dialog_play calls for dialogue. Why didn't BWest always do it that way? Again it may be due to a change in the functionality of sound_dialog_play_block during development. But occasionally it may be desirable to separate the playing of a dialogue line from the command to block on it, for instance if you want to perform some actions immediately after starting a line playing, <u>then</u> block until the line finishes, then perform additional actions before playing further dialogue.''
*sound_dialog_play_interrupt name:string - function to interrupt the current character dialog and play a new one - sound_dialog_play_interrupt c00_01_66shinatama
*sound_dialog_play_interrupt name:string - function to interrupt the current character dialog and play a new one - sound_dialog_play_interrupt c00_01_66shinatama
*sound_impulse_play name:string [volume:float] - function plays an impulse sound - sound_impulse_play glass_big 1.0
*sound_impulse_play name:string [volume:float] - function plays an impulse sound - sound_impulse_play glass_big 1.0
''Works with all "imp.oni" files extracted (or created) with OniSplit.''
*sound_list_broken_links - function writes a list of sounds which have broken links to a file
*sound_list_broken_links - function writes a list of sounds which have broken links to a file
*sound_music_start name:string [volume:float] - function to start music playing - sound_music_start mus_asian 0.75
*sound_music_start name:string [volume:float] - function to start music playing - sound_music_start mus_asian 0.75
Line 463: Line 444:
*timer_stop (null) - stops the countdown timer - timer_stop
*timer_stop (null) - stops the countdown timer - timer_stop


===laser triggers===
===triggers (lasers)===
*trig_activate trigger_id:int - activates a trigger - trig_activate 2
*trig_activate trigger_id:int - activates a trigger - trig_activate 2
*trig_deactivate trigger_id:int - deactivates a trigger - trig_deactivate 2
*trig_deactivate trigger_id:int - deactivates a trigger - trig_deactivate 2
Line 495: Line 476:
*weapon_spawn weapontype:string flag:int - creates a new weapon - weapon_spawn w3_phr 7045
*weapon_spawn weapontype:string flag:int - creates a new weapon - weapon_spawn w3_phr 7045


[[Category:Bungie scripting language docs]]
[[Category:BSL docs]]
Retrieved from "https://wiki.oni2.net/Special:MobileDiff/23567...42836"