Internal buttons.js

From Spheriki

internal_buttons.js is a custom script by Sulphur21. The InternalButton object it provides (abrev. IB) represents both, a key and a joystick button. In practice it can be used similar to a normal key. I.e. you can check different types of states (pressed, triggered, hit), bind the IB to a script or use it for talk activation. The advantage compared to Sphere's standard input handling functions is easier handling of joystick input and easier input customization in general. You can modify the key and joystick button assigned to an IB at any time you want, while your routines keep on checking for the state of just the IB object without caring for the assignation.

Important note: The current version of this script is not compatible to Sphere 1.5 (or higher)!

Contents 1 Download and inclusion of the script 2 Creating an InternalButton object 3 How to modify it 4 How to check its state 5 How to bind scripts and use talk activation

Download and inclusion of the script

Download internal_buttons.js.txt, rename the file to internal_buttons.js and copy it into the scripts folder of your project. The license of the script has been placed on top of the script code. Read it before using the script. Then place this on top of your main script:

 RequireScript("internal_buttons.js");

Creating an InternalButton object

Here's how to call the constructor that returns an InternalButton object:

• some_name = new InternalButton(key, joystick, button)

If one or more of the three parameters remain undefined, that'll be ok. Apart from regular joystick button numbers, you can use JOYSTICK_UP, JOYSTICK_RIGHT, JOYSTICK_DOWN or JOYSTICK_LEFT to assign a joystick direction to an IB.

Examples:

 var MyIB1 = new InternalButton(KEY_W, 0, 3);
 var MyIB2 = new InternalButton(KEY_UP, 0, JOYSTICK_UP);

Now MyIB1 has KEY_W on the keyboard and button 3 of joystick 0 assigned to it. MyIB2 has the up key and the up direction of joystick 0 assigned to it.

How to modify it

You can always modify an IB's key, joystick and (joystick) button. They're properties of any InternalButton object. You can even modify them while you use the IB as a TalkAcivationIB or while you have scripts bound to its pressing or release (see below). It'll work just fine.

Example:

 //This creates an IB with just a key assigned to it.
 var MyIB3 = new InternalButton(KEY_ENTER);
 
 //This modifies the key and adds a joystick button.
 MyIB3.key      = KEY_SHIFT;
 MyIB3.joystick = 0;
 MyIB3.button   = 3;

How to check its state

To check the state of an IB you'll need to update its flags first.

• InternalButton.updateFlags() updates the three flags which are described below. Their value can be either true or false.
• InternalButton.isPressed is true, if the IB, that means its key and/or its button, is being pressed.
• InternalButton.isHit is true once if the IB is newly hit, but becomes false if it is held down afterwards (just as if it was imediately released).
• InternalButton.isTriggered is true once if the IB is newly hit. If it is held down, it is set to true in certain intervals. In between it is false. It works similar to the way a key that you hold down returns letters in an editor.

Here's an example. It creates a menu arrow (without an actual menu) that can be moved using the up/down direcs (via keyboard or joystick). Note that it uses the isTriggered flag. Compare what happens to the arrow movement if you hold down the up/down direcs after exchanging isTriggered with isHit: You'll have to release the key/button after each hit and press it again to move the arrow. For the sake of interest try using isPressed to check the IB state in the example and you'll see why it's not really useful in this case. ;)

 //This includes the script.
 RequireScript("internal_buttons.js");
 
 // This creates the required IBs.
 var IB_UP      = new InternalButton(KEY_UP,     0, JOYSTICK_UP);
 var IB_DOWN    = new InternalButton(KEY_DOWN,   0, JOYSTICK_DOWN);
 var IB_DONE    = new InternalButton(KEY_ESCAPE, 0, 0);
 
 // This loads the system arrow graphic.
 var Arrow      = GetSystemArrow();
 
 // This runs the "menu".
 function game() {
   var ArrowPosition = 0;     // Currently selected "menu entry".

   while (!IB_DONE.isTriggered) {
 
     // Check if up has been triggered and move arrow accordingly.
     IB_UP.updateFlags();
     if (IB_UP.isTriggered) {
       ArrowPosition -= Arrow.height;
     }
 
     // Check if down has been triggered and move arrow accordingly.
     IB_DOWN.updateFlags();
     if (IB_DOWN.isTriggered) {
       ArrowPosition += Arrow.height;
     }
    
     // Update IB_DONE.
     IB_DONE.updateFlags();
    
     // Render Arrow
     Arrow.blit(0, ArrowPosition);
     FlipScreen();
   }
 }

How to bind scripts and use talk activation

The following will be of interest, if you're using Sphere's standard input handler [see AttachInput()].

Each IB has an onPress and an onRelease property. They hold simple scripts in string format which are assigned to an IB just like BindKey() and BindJoystickButton() assign scripts to keys and joystick buttons. Note that the joypad directionals (JOYPAD_UP, etc.) won't work for that.

To use an IB for talk activation assign it to the global var TalkActivationIB. Note that it must have a key and a joystick button assigned to it and must use joystick 0. Joypad directionals won't work here as well. This is due to the restrictions of Sphere's standard input handler.

It is highly recommended not to use SetTalkActivationKey(), SetTalkActivationButton(), BindKey, BindJoystickButton(), UnbindKey() and UnbindJoystickButton() if you're using the above IB properties, for they might interfere and confuse each other.

The examples show that it is enough to assign values to the properties. You won't need to call any functions to make things work.

 // This'll make MyIB4 be the talk activator in map mode.
 var MyIB4        = new InternalButton(KEY_ENTER, 0, 0);
 TalkActivationIB = MyIB4;
 
 // This'll make MyIB5 run SomeFunction() if pressed during map mode.
 var MyIB5        = new InternalButton(KEY_SPACE, 0, 2);
 MyIb5.onPress    = "SomeFunction()";