DimensioneX Change language Custom Panels


Home
Features
Play Online
Download
Forum
Tutorial
Documentation
Wiki
Support
Resources
Members
Gadgets
Contacts
Links






free screen-saver
Fantasy Screensavers and Desktop Backgrounds

 


DimensioneX on SourceForge.net

 

Defining and using custom panels 
and custom graphic buttons

KB Article n. 016
Date: Oct, 13th, 2003
Originally for: DimensioneX 5.1.1

Abstract

This article explains how to define and use custom commands panels and custom graphic buttons.

 

Introduction

Since version 5.0.9, DimensioneX supports custom controls. This feature was introduced to allow game designers to override the standard game controls panel, and define custom buttons sets, as well as a set of custom events with which the clicked buttons could be interpreted and managed during game run-time.

Target behaviour

In our example, we'll explore this feature by assuming we have a game in which we need the player to be capable following game commands:

Roll the dice! Used as a stand-alone command (i.e. needs no more parameters), would be used to produce a random number from 1 to 6 and display it on the screen of all players in the game. This command will be used for using DimensioneX as an on-line platform to play RPG games the ordinary way.
Attack #1 Used with one parameter, specifies that the player wants to attack another character. The character to be attacked (#1) will be selected after the command. 
Cut #1 with #2 Used with two parameters, specifies that the player wants to cut object #1 with object #2. The two objects will be selected after the command.
Magic formula "XYZ" Pronounces a magic formula (XYZ) to be specified in a textbox. Some specific magic formulas will produce effects, others will not.

The four examples above represent all possible combination of parameters so it is important that you follow all this tutorial.

Step 1 - Defining the panel

You start by taking a sample game on which to take the next steps.
Please open with your favourite text editor the world2.dxw file you will find in your DimensioneX package. Perhaps you will want to work on a copy of it, so that you keep the original one for other, later experiments.

Please remember that when testing your work, in order to let DimensioneX engine to run this file, you will have to edit the worldnav.properties file and change the worldFile setting accordingly.

Now, the first question one should ask himself is the following:

Am I willing to:

a) redefine the standard, default commands panel? or 

b) use the custom commands only in selected rooms/situations?

For this tutorial we will suppose here that we are in case a)

Case b), though, can also be easily managed after understanding this tutorial. Just read the information contained in the Programmers' Reference, which you should always keep at hand.

In World2 the standard panel named "chat" is loaded at the startup. You can't do much with it.

As soon as you arrive at the bungalow, you will notice there's a switch there. As soon as you USE the switch another "default" panel is loaded so that all players are able to play and finish the simple game, whose objective is to pick up an apple contained in a box located around. It is suggested that you have a test round in World2 so that you understand how it works.

In this tutorial, we will re-define the default commands panel so that the new commands (Roll the dice, attack, hit and magic formula) are available. For doing this, we will insert a GUI section, right after the WORLD opening tag, and a PANEL definition inside:

GUI

PANEL default 
    BUTTON open
    BUTTON pick
    CR
    BUTTON logout
    BUTTON help

END_GUI

The above code re-defines the default panel, and reuses standard buttons allowing basic commands so that the game an be finished.

Save and verify. As soon as you activate the switch your test game will look like this:

You should still be able to finish the simple adventure with this, custom reduced panel. Now let's define the new commands.

Step 2 - Defining the commands - basic level

Now let's fill the PANEL definition with BUTTONS so that the commands we need get realised.

Zero parameters - "Roll the dice" command

this is the typical case of a command which needs no parameters. The definition of a custom button for it could be the following one, written in bold face:

PANEL default
    BUTTON roll, "Roll the Dice", "Roll the dice now!", onDiceRoll
    CR
    BUTTON open
    BUTTON pick
    CR
    BUTTON logout
    BUTTON help

We also added a CR tag, so that a carriage return is inserted.
After the BUTTON tag, we have a unique identifier (roll) which will be used internally in the player's client. We are not very interested in it, but we need to specify it so that the button can be distinguished and re-used in the future.
Then, we have spcified the label on the buttons' surface ("Roll the Dice"), then the toolbar tips text (nearly identical!), finally the name of a custom event (onDiceRoll) which we will exploit in order to detect when the button has been clicked. So, let's add the following EVENT in the EVENTS section before the END_WORLD closing tag. You should just copy+paste the part written in bold:

EVENTS
...
EVENT onDiceRoll
ACTIONS
    nr = rndInt(6)
    Broadcast $AGENT.name + " has rolled the dice and the result is " + nr

END_EVENTS

Please note that we inserted a carriage return (CR) in the PANEL definition in order to get a better layout.

Save and test. You are now able to roll the dice and all the connected players will be able to see the result of the dice roll.

One parameter - "Attack" command

this is the typical case of a command which needs one parameter. The definition of a custom button for it could be the following one, just insert it somewhere inside the PANEL definition:

BUTTON attack, "Attack", "Attack ...", onAttack, O

The need for a parameter is expressed after the custom event ID (onAttack), by means of the code "O" (O stands for Object). Please note that the toolbar tip text has dots which will be automatically replaced by the actually selected object. The EVENT which could manage the user input could be the following:

EVENT onAttack
ACTIONS
    Display "Owner=" + $OWNER + " Agent=" + $AGENT + " Target=" + $TARGET
    Display $AGENT.name + " is attacking " + $OWNER.name

The code actually prints out the system variables and then a simple message telling who is attacking who. Then the code for a battle can be written your own.

Tip: If you need it, you may want to take the attack/battle code from the game "Underworld" and adapt it to your needs.

Step 3 - Defining the commands - advanced level

Two parameters - "Cut" command

this is the typical case of a command which needs two parameter. The first object which is clicked represents the one to be cut. It will be the OWNER object of the specified event. The second object which is clicked represents the one to be used as a tool.

First of all we would rather add a tool which could be used to cut:

ITEM scissors
NAME scissors
DESCRIPTION A pair of scissors with sharp blades.
ICON icoScissors.gif
POSITION spiaggia
ATTRLIST pickable
IMAGE 100x73 scissors.gif
SHOW ICON

Now we have a nice scissors on the beach.
Next, the definition of a custom button for it could be the following one, written in bold face:

BUTTON cut, "Cut with", "Cut ... with ...", onCut, OO

The need for two parameters is expressed after the custom event ID (onCut), by means of the code "OO" (OO stands for Object+Object). Please note that the toolbar tip text has dots which will be automatically replaced by the actually selected object. 

Finally, we need an EVENT which could manage the user input.

The code could be the following:

EVENT onCut
ACTIONS
    Speak "Owner=" + $OWNER + " Agent=" + $AGENT + " Target=" + $TARGET
    If $OWNER=box And $TARGET=scissors
    	box.description = "This box is broken with a straight cut."
    	DropItems box
    Else
    	Display "Doesn't work!"
    End_If

The code actually prints out the system variables. Then it checks for the combination: scissors on box. If it matches, the box's description is altered and the items contained in the box are dropped to the ground. Any other combination of CUT command with other objects produces a "Doesn't work!" message.

Note: Please note that, in "OO" custom commands, the second object (the scissors) always is identified as $TARGET, even though in the real world the box is actually the target of the performed action. Don't be fooled by parameters names, the first line of code provided in this example should always be used to correctly figure out how parameters are dealt with.

One text and one parameter - "Magic formula" command

There are cases in which you need a user-entered, text parameter in addition to one game object.
This is the case of the "Magic formula" command: with this one, you pronounce a magic formula which will be used on a game object and possibly produce a result. The result is obviously dependent to the EVENT handling code. First, let's define the command:

CR
TEXTBOX
BUTTON spell, "Magic to", "Cast formula ... on ...", onMagic, TO
CR

The CR are just to insert spacing. The TEXTBOX is necessary to let the user write the magic formula. Then, the button is nothing new when compared to the previous examples, except that it uses parameter model "TO" (TO stands for Text+Object) telling the client that the first parameter is actually taken from the textbox.

The handling EVENT code could be the following:

EVENT onMagic
ACTIONS
    Display "Owner=" + $OWNER + " Agent=" + $AGENT + " Target=" + $TARGET
    If $TARGET = "vanish"
    	Kill $OWNER
    Else
    	Display "Nothing happens."
    End_If

You will notice how the "vanish" magic formula will make any object to disappear, while "abracadabra" does nothing!

Note: Please note that, in "TO" custom commands, the parameters are automatically inverted, so that the specified object is always is identified by $OWNER, and the user-specified text is always contained in the $TARGET even though in the real world the surfer was actually the target of the performed action. Again, don't be fooled by parameters names, the first line of code provided in this example should always be used to correctly figure out how parameters are dealt with.

Step 4 - Defining graphic buttons

We will now replace the standard grey button we inserted at the end of the previous step, by replacing it with a custom, graphic button. 

The button would be the following:

Right-click on it and choose "Save image as..." to save the image in your DimensioneX pics folder (you should be able to find it in your DimensioneX installation tree".

Now, here's how the BUTTON specification has to be changed: just add an IMAGE tag at the end.

BUTTON spell, "Magic to", "Cast magic formula ... on ...", onMagic, TO
    	IMAGE	64x20	btnspell.gif

Easy! The text which was used to show on the button's surface is now used for balloon tips. All the rest is left unchanged.

For your custom buttons you can use any graphic file you like, as long as the browsers recognise it (JPG, GIF and PNG formats are okay).

Done!

This tutorial is over. 

If you're in doubt, the complete source can be found here.

Feel free to contact us or post on the forums to give us some feedback or ask for more advice.