forked from Mirrors/openclonk
Add and update documentation for all control changes
Lukas Werling
parent
7155ff90eb
commit
9e9505fdf3
|
|
@ -273,7 +273,7 @@
|
|||
return true;
|
||||
}</code>
|
||||
<text>most commands (except for asynchronous commands in the player menu) call a global script function:</text>
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)</code>
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, int state)</code>
|
||||
<text>For an explanation of the parameters see <funclink>PlayerControl</funclink>. Amongst others, the function receives the calling player in player as well as the command to be executed in control.</text>
|
||||
<text>As a simple example let's assume that in the global <em>PlayerControls.txt</em> the following command has been defined:</text>
|
||||
<code>[ControlDefs]
|
||||
|
|
@ -293,11 +293,11 @@
|
|||
Control=Jump
|
||||
Priority=50</code>
|
||||
<text>This defines a Jump key and the corresponding standard mapping on the keyboard for the first player. The following script is used to handle the control:</text>
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, int state)
|
||||
{
|
||||
// Which command has been issued?
|
||||
// The constant CON_Jump has been declared automatically through the definition in PlayerControls.txt
|
||||
if (control == CON_Jump && !release)
|
||||
if (control == CON_Jump && state == CONS_Down)
|
||||
{
|
||||
// pressed the jump button. The clonk selected by the player shall jump
|
||||
var player_clonk = GetCursor(player);
|
||||
|
|
@ -319,17 +319,17 @@
|
|||
GUIDesc=Going underground
|
||||
ExtraData=Shovel</code>
|
||||
<text>Let shovel be the ID of a shovel object. In the global script there could be the following, generic handling for unknown commands, for example:</text>
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, int state)
|
||||
{
|
||||
// Handling of known controls
|
||||
// [...]
|
||||
// control with own handling
|
||||
if (control_extra) return control_extra->PlayerControl(player, control, x, y, strength, repeat, release);
|
||||
if (control_extra) return control_extra->PlayerControl(player, control, x, y, strength, repeat, state);
|
||||
// unkown control
|
||||
return false;
|
||||
}</code>
|
||||
<text>And in the script of the shovel:</text>
|
||||
<code>func PlayerControl(int player, int control, int x, int y, int strength, bool repeated, bool release)
|
||||
<code>func PlayerControl(int player, int control, int x, int y, int strength, bool repeated, int state)
|
||||
{
|
||||
// Handling of known controls
|
||||
// Control dig directly in the shovel
|
||||
|
|
@ -353,6 +353,7 @@
|
|||
<li>Mappings can emulate permanent key presses using the <em>Hold</em>/<em>Release</em> flags.</li>
|
||||
<li><emlink href="playercontrols.xml#Repeat">Key repeats</emlink> are generated.</li>
|
||||
<li>The held state of the key can be queried in the script via <funclink>GetPlayerControlState</funclink>.</li>
|
||||
<li>If the command is bound to an analog stick or trigger on a controller, every change in position causes in a call to PlayerControl() with state = CONS_Moved.</li>
|
||||
</ul>
|
||||
</text>
|
||||
<text>A good example for this functionality is a directional command:</text>
|
||||
|
|
@ -362,7 +363,7 @@
|
|||
GUIDesc=Walk left
|
||||
Hold=1</code>
|
||||
<text>In the script the direction is transferred to the Clonk:</text>
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
|
||||
<code>global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, int state)
|
||||
{
|
||||
if (control == CON_Left) return UpdateControlDir(player);
|
||||
// ...
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<func>
|
||||
<title>GetPlayerControlState</title>
|
||||
<category>Player</category>
|
||||
<version>5.1 OC</version>
|
||||
<version>5.1 OC (extended in 8.0 OC)</version>
|
||||
<syntax>
|
||||
<rtype>int</rtype>
|
||||
<params>
|
||||
|
|
@ -20,9 +20,15 @@
|
|||
<name>control</name>
|
||||
<desc>Control to query. A CON_* constant should be used here.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>bool</type>
|
||||
<name>analog_strength</name>
|
||||
<desc>If true: Query current state of an analog control on a gamepad instead of the emulated button state.</desc>
|
||||
<optional />
|
||||
</param>
|
||||
</params>
|
||||
</syntax>
|
||||
<desc>Returns the current state of a control for a certain player. The return value is the strength of the control (e.g. for gamepad joysticks). If the control is assigned to a key, a value not equal to 0 means that the key is currently held down by the player.</desc>
|
||||
<desc>Returns the current state of a control for a certain player. If the control is assigned to a key, a value not equal to 0 means that the key is currently held down by the player. For analog controls on gamepads, the function either queries the current emulated button state (analog_strength = false), or the current position of the stick or trigger (analog_strength = true).</desc>
|
||||
<examples>
|
||||
<example>
|
||||
<code>
|
||||
|
|
@ -36,4 +42,5 @@ if (GetPlayerControlState(GetOwner(), CON_Left) != 0)
|
|||
</related>
|
||||
</func>
|
||||
<author>Zapper</author><date>2015-10</date>
|
||||
<author>Luchs</author><date>2016-02</date>
|
||||
</funcs>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<!DOCTYPE funcs
|
||||
SYSTEM '../../../clonk.dtd'>
|
||||
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
|
||||
<funcs>
|
||||
<func>
|
||||
<title>PlayRumble</title>
|
||||
<category>Player</category>
|
||||
<version>8.0 OC</version>
|
||||
<syntax>
|
||||
<rtype>bool</rtype>
|
||||
<params>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>player</name>
|
||||
<desc>Number of the player whose controller should rumble. Can be NO_OWNER to make all controllers rumble.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>strength</name>
|
||||
<desc>Strength of the rumble, between 0 and 1000.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>length</name>
|
||||
<desc>Duration of the rumble in milliseconds.</desc>
|
||||
</param>
|
||||
</params>
|
||||
</syntax>
|
||||
<desc>Plays a haptic effect on the given player's gamepad. Returns true if all parameters are valid; there is no way to know whether the rumble was actually played.</desc>
|
||||
<examples>
|
||||
<example>
|
||||
<code>
|
||||
<funclink>ShakeObjects</funclink>(<funclink>LandscapeWidth</funclink>()/2, <funclink>LandscapeHeight</funclink>()/2, <funclink>Distance</funclink>(<funclink>LandscapeWidth</funclink>(), <funclink>LandscapeHeight</funclink>())/2);
|
||||
PlayRumble(NO_OWNER, 1000, 2000);
|
||||
</code>
|
||||
<text>Earthquake: Shakes all Clonks and rumbles all controllers at full strength for two seconds.</text>
|
||||
</example>
|
||||
</examples>
|
||||
<related>
|
||||
<funclink>StopRumble</funclink>
|
||||
</related>
|
||||
</func>
|
||||
<author>Luchs</author><date>2016-02</date>
|
||||
</funcs>
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<!DOCTYPE funcs
|
||||
SYSTEM '../../../clonk.dtd'>
|
||||
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
|
||||
<funcs>
|
||||
<func>
|
||||
<title>PlayerControl</title>
|
||||
<category>Callbacks</category>
|
||||
<version>5.1 OC</version>
|
||||
<syntax>
|
||||
<rtype>bool</rtype>
|
||||
<params>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>player</name>
|
||||
<desc>Number of the player who pressed the control.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>control</name>
|
||||
<desc>Number of the pressed control, defined as a CON_ constant via PlayerControls.txt.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>id</type>
|
||||
<name>control_extra</name>
|
||||
<desc>Optional id defined with ExtraData in PlayerControls.txt.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>x</name>
|
||||
<desc>X coordinate for mouse controls.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>y</name>
|
||||
<desc>Y coordinate for mouse controls.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>strength</name>
|
||||
<desc>Current strength of the control. For key presses: 0 or 100. For analog stick or trigger movement (state = CONS_Moved): 0-32768.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>bool</type>
|
||||
<name>repeated</name>
|
||||
<desc>Whether the call is generated because of a held button.</desc>
|
||||
</param>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>state</name>
|
||||
<desc>
|
||||
State of the key press. Possible values:
|
||||
<table>
|
||||
<rowh>
|
||||
<col>Constant</col>
|
||||
<col>Description</col>
|
||||
</rowh>
|
||||
<row>
|
||||
<literal_col>CONS_Down</literal_col>
|
||||
<col>Key has been pressed down.</col>
|
||||
</row>
|
||||
<row>
|
||||
<literal_col>CONS_Up</literal_col>
|
||||
<col>Key has been released. Only generated for held keys.</col>
|
||||
</row>
|
||||
<row>
|
||||
<literal_col>CONS_Moved</literal_col>
|
||||
<col>An analog control on a gamepad has been moved. Only generated for held keys.</col>
|
||||
</row>
|
||||
</table>
|
||||
</desc>
|
||||
</param>
|
||||
</params>
|
||||
</syntax>
|
||||
<desc>Called globally for each control command by players. See <emlink href="script/playercontrols.html">Player Controls</emlink>.</desc>
|
||||
<related><funclink>GetPlayerControlState</funclink></related>
|
||||
<related><emlink href="playercontrols.html">Player Controls</emlink></related>
|
||||
</func>
|
||||
<author>Luchs</author><date>2016-02</date>
|
||||
</funcs>
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<!DOCTYPE funcs
|
||||
SYSTEM '../../../clonk.dtd'>
|
||||
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
|
||||
<funcs>
|
||||
<func>
|
||||
<title>StopRumble</title>
|
||||
<category>Player</category>
|
||||
<version>8.0 OC</version>
|
||||
<syntax>
|
||||
<rtype>bool</rtype>
|
||||
<params>
|
||||
<param>
|
||||
<type>int</type>
|
||||
<name>player</name>
|
||||
<desc>Number of the player whose controller should stop rumbling. Can be NO_OWNER to make all controllers stop.</desc>
|
||||
</param>
|
||||
</params>
|
||||
</syntax>
|
||||
<desc>Stops a rumble effect that was started with <funclink>PlayRumble</funclink>. Returns true if the given player is valid; there is no way to know whether there was actually a playing rumble effect.</desc>
|
||||
<related>
|
||||
<funclink>PlayRumble</funclink>
|
||||
</related>
|
||||
</func>
|
||||
<author>Luchs</author><date>2016-02</date>
|
||||
</funcs>
|
||||
Loading…
Reference in New Issue