Any PANEL definition must be placed in the GUI section and defines a controls panel (forms) to be used in the game.
GUI section’s syntax is as follows (square brackets indicate optional parts):
PANEL panelId [VERSION OF parentPanelId]
[BUTTON definition | CR definition | MAP definition | TEXTBOX definition | LABEL definition | DROPDOWN definition | DELETE spec | CMD spec ]
[more control definitions…]
The VERSION OF tag may be added to build a modified version of an existing panel, so that you just add additional controls, or delete existing ones.
| Parameters | Meaning |
| panelId | Identifier of the panel (mandatory)
If the panelId identifier represents an existing panel, the new definition will replace the existing one. Note: “default“, “chat“, “connecting” and “exiting” are IDs of pre-defined panels. “connecting” is the panel to be used while connecting. “exiting” is the panel used when a “Save and Exit” command is used. |
| parentPanelId | (Optional) Identifier of an existing panel from which commands should be imported. |
As it should be clear, a PANEL tag just specifies the PANEL’s id for later reference, and acts as a container for the controls’ specifications. For more information about them, see 2.5.2 – How PANELs work.
2.5.1 Pre-defined PANELs
DimensioneX has got a number of pre-defined PANELS which, in turn, consist of pre-defined controls.
Please remember that all defined PANELs can be inspected by using the DimensioneX Administrator’s screen, selecting Snapshot and then Panels.
| panel id | what is it? | built-in control IDs |
| Default | It is the panel used normally – all commands available. | go, look, use, use2, _sep4, open, close, pick, drop, _sep9, search, hide, put, give, _sep14, enter, exit, _sep17, _sep18, txtBox, say, _sep21, _sep22, clear, help, _sep25, save,savexit, logout |
| Chat | It is a simplified panel, useful for chatting and little else | go, look, _ctr2, _sep3, txtBox, _sep5, _sep6, use, _sep8, _sep9, help, savexit, logout
|
| Connect | Initial connect screen | go, look, lbl0, username, _sep4, lbl1, skin, _sep7, lbl2, audio, _sep10, lbl3, music, _sep13, lbl4, screensize, _sep16, _sep17, help, login, lbl5, lbl6 |
| Connecting | It is used by the system when connecting with a saved profile | go, look, lbl0, _sep3, pass, _sep5, _sep6, login, _sep8, _sep9, startscratch, cmd, _sep12, _sep13, return, _sep15, _sep16, help |
| Exiting | It is used by the system when doing “Save and Exit” | go, look, lbl1, txtBox, _sep4, _sep5, savexit, _sep7, return, _sep9, help |
Note:
- _sep*** in the above table are separators (line breaks).
- Labels for the built-in controls of the pre-defined PANELs are directly taken from the msgs_xxx.properties language file.
- pre-defined controls (look, open, etc…) will trigger pre-defined EVENTs. Currently there’s no documentation on this. So, to know exactly which EVENT is triggered by each command, you should simply use the command and then look on the log file to see which EVENT is triggered (loof for “world.fireEvent”).
2.5.2 How PANELs work
- Each game (or WORLD) at startup is initialized so that it uses the default
- Each connecting player may have a player-scpecific commands panel. However, this player-specific commands panel is not set by default.
When a player is in the game, the controls he or she sees are determined by the following:
- player-specific commands (optional, as for point b above)
plus (+)
- room-specific commands (optional). If these are missing, then the commands from the world’s current PANEL is used (normally the default one as specified in point a above).
The world’s current panel can be changed via the SetPanel instruction (see SmallBasic guide, below)
Also the player’s specific or room’s specific panels can also be changed via the setPanel instruction.
The combination of specific, and WORLD-wide panels gives the game programmer a great flexibility and power.
2.5.3 BUTTON definition
BUTTON defines a command button inside a PANEL definition.
The syntax depends on what button you need, as follows:
Syntax #1, for standard buttons:
BUTTON id,”Label”,”ToolTipText”, Event [,EventModel]
Syntax #2, for ICON-enhanced buttons:
BUTTON id,”BalloonText”,”ToolTipText”, Event [,EventModel]
ICON src
Syntax #3, for IMAGE buttons:
BUTTON id,”BalloonText”,”ToolTipText”, Event [,EventModel]
IMAGE [widthxheight] src
Syntax #4, for quick import from default panel
BUTTON id
[ICON src]
Syntax #1 is the standard one.
Syntax #2 is a the recommended one. You specify an icon to be shown starting from the upper-left corner of the button. The icon is typically a 16×16 transparent GIF image (but you can actually use imges of any size and type depending on the effect you want to achieve). This syntax will cope with multiple languages and colours.
Syntax #3 adds a line for specifying the buttons’ IMAGE. Consult 2.10 – IMAGE at page 49 for more information on the IMAGE definition.
Syntax #4 is also said “quick definition”. It is used to quickly reference a standard, existing BUTTON control which is present in the “default” commands PANEL without having to re-define it. The commands look, by example, must be included in all panels so this syntax can be used to quickly do the job. Also the command logout, savexit, help may be useful to include.
You can also specify an ICON tag so that an icon is added to standard commands.
| Parameters | Meaning |
| Id | Identifier of the button (mandatory) Note: The following Ids have a special meaning and are automatically dealt with by the DimensioneX Javascript client. Don’t use these ones if you would like to implement different, custom commands:look, go, logout, savexit, return, rotate, use, use2, drop, pick, put, give, say, search, hide, clear, rotr, rotlYou can use the above, however, to change the look of the buttons but you won’t be able to change the command’s standard behaviour. |
| Label | Text of the button as it will appear on the command panel. Double quotes recommended. |
| BalloonText | Text which will appear in the yellow balloon hints when pausing with the mouse on an IMAGE button’s surface. Same as for Label. |
| ToolTipText | Tip text for the toolbar hints. Double quotes are mandatory.
The triple dots are automatically handled by the client and substituted with actual object names. A typical Tip Text are “Attack …” “Trade … with …” “Give … with …” and so on. |
| Event | ID of for the event or full function call to be triggered when the command is used. If you specify parameters separated by commas, you MUST place the code between double quotes. |
| EventModel | Describes what parameters the command uses and how they are mapped into the owner/target variables according to the DimensioneX avent model. Values can be one of the following:
(none) : no parameters O : 1 object parameter (owner) OO : 2 object parameters (owner, target) T : 1 text parameter (target) TO : 1 text parameter, 1 object parameter (target, owner) |
Here is an example, which defines a control which rolls a dice, and includes the code for the associated EVENT to exploit this new custom command:
GUIPANEL default
BUTTON create, “Create Object”, “Create Object!”, onCreate
BUTTON destroy, “Destroy Object”, “Destroy Object!”, onDestroy
BUTTON rolldice, “Roll Dice”, “Roll Dice!”, onRollDice
BUTTON look
BUTTON logout
END_GUI
…
SCRIPTS
EVENT onRollDice
nr = rndInt(6)
Speak SYS,$WORLD,$AGENT.name + ” has rolled the dice and the result is ” + nr
END_SCRIPTS
Another example, showing how a full function call can be used in Event. Here, the doAffinity sub is used to handle all four buttons, in fact the working logic is depending on the value of the four parameters.
PANEL paffinityBUTTON waterplus, “+”, “Command”, “doAffinity(1,0,0,0)”
BUTTON water, “Water”, “Water”, helpAffi
IMAGE 32×32 elem1.gif
LABEL ” Water”
BUTTON waterminus, “-“, “Command”, “doAffinity(-1,0,0,0)”
LABEL “<BR />”
BUTTON earthplus, “+”, “Command”, “doAffinity(0,1,0,0)”
BUTTON earth, “Earth”, “Earth”, helpAffi
IMAGE 32×32 elem2.gif
LABEL ” Earth”
BUTTON earthminus, “-“, “Command”, “doAffinity(0,-1,0,0)”
LABEL “<BR />”
BUTTON windplus, “+”, “Command”, “doAffinity(0,0,1,0)”
BUTTON wind, “Wind”, “Wind”, helpAffi
IMAGE 32×32 elem3.gif
LABEL ” Wind”
BUTTON windminus, “-“, “Command”, “doAffinity(0,0,-1,0)”
LABEL “<BR />”
BUTTON fireplus, “+”, “Command”, “doAffinity(0,0,0,1)”
BUTTON fire, “Fire”, “Fire”, helpAffi
IMAGE 32×32 elem4.gif
LABEL ” Fire”
BUTTON fireminus, “-“, “Command”, “doAffinity(0,0,0,-1)”
LABEL “<BR /><BR /><INPUT TYPE=hidden NAME=affi VALUE=1>”
BUTTON dothis,”Done”,”Command”, doCommand
Sub doAffinity(e1,e2,e3,e4)
‘Event code…
End_Sub
2.5.4 CR definition
CR defines a carriage return inside a PANEL definition. The syntax is simply as follows:
CR
2.5.5 MAP definition
MAP defines a map box inside a PANEL definition. The syntax is simply as follows:
MAP
The map image to be displayed must be defined in the GUI section by means of the MAP tag and can be changed according to any room by using the room’s map attribute.
2.5.6 TEXTBOX definition
TEXTBOX defines a text box inside a PANEL definition. The syntax is as follows:
TEXTBOX [id]
The id is optional and will be returned as a key in the input( ) set. If omitted, ir defaults to “txtBox”
2.5.7 LABEL definition
LABEL defines a label inside a PANEL definition. The syntax is simply as follows:
LABEL “free text“
Note: HTML code can be inserted inside double quotes. This element is indeed very powerful as it can be used to create very special panels, provided you have understood how the Javascript in the player’s client works.
2.5.8 DROPDOWN definition
DROPDOWN defines a drop-down list inside a PANEL definition. The syntax is:
DROPDOWN id,Set,Default [,WorkingModel]
| Parameters | Meaning |
| Id | Identifier of the control (mandatory) Avoid conflicts with reserved (and other custom) control IDs |
| Set | Expression to be evaluated at run-time which must return a SET containing identifiers and decriptions or an ARRAY containing decriptions to be used for building the dropdown list.
You can use $OWNER to reference the player. For complex expressions you must enclose the expression between quotes, otherwise you will get an error. Example: “$OWNER.setChoices” is a valid expression, $OWNER.setChoices will report that there is an unexpected dot. |
| Default | Expression to be evaluated at run-time which should (theoretically) be one of the Ids of the Set. If so, the corresponding element will be pre-selected.
Note: If Set will result in an ARRAY then this must be a zero-padded number of four digits. Example : 0002 sets the second element of the array as the default. You can use $OWNER to reference the player. For complex expressions you must enclose the expression between quotes, otherwise you will get an error. |
| WorkingModel | (Optional) Sets the working mode.
Possible values: AUTOSUBMIT
Note: In this release this setting will not produce any result. This functionality will be implemented in future releases. |
2.5.9 DELETE specification
DELETE removes an existing control from the panel:
The syntax is:
DELETE id
| Parameters | Meaning |
| Id | Identifier of the control to be removed (mandatory) |
In the following example, we modify the connect panel so that it fits a horizontal frame:
PANEL connect VERSION OF connectCR
DELETE _sep3
DELETE _sep4
2.5.10 CMD specification
CMD defines a generic command inside a PANEL. The control will not be visible in the user interface but the control ID will be managed client script and therefore by the game engine. An example of this is the “click” command, triggered by the client when an object is clicked. The game engine currently maps this command to a “look” command automatically, but it has differences with an explicit look command.
We obviously do not want a “click” button to appear in the user interface so the game engine uses this type of definition to map the click command into the default PANEL.
syntax is:
CMD id
| Parameters | Meaning |
| Id | Identifier of the control (mandatory) Avoid conflicts with reserved (and other custom) control IDs |