How the guild system works - game: Underworld
The guilds system is a small application within the Underworld game, built thanks to two features of DimensioneX: the support for SET objects and the SaveSetting/LoadSetting instructions.
This article refers to version 6.9.5 of [Underworld], and to DimensioneX version 6.1.0.
If you have other versions of the software you could meet some inaccuracies. Being this article hosted on a WIKI site, you can correct errors by using the EDIT tab or eave comments by using the DISCUSSION tab.
1 the guilds room
Everything starts from a room ( guildroom ), that is where the application runs mostly.
I have created this special room (tower the south-west) and a specific character ( Lord Guilford ) who has the purpose to dispatch to the user a message in case he/she does something wrong.
ROOM guildroom NAME Southwest room DESCRIPTION This the room of the guards' captain. He knows about all existing Guilds. IMAGE S armoroom2.jpg PANEL pguilds
In this room we will manage the guilds, that's why in the definition of the room I have specified that it uses a special panel "pguilds" about which we will speak now
2 the panel
To make it possible to manage guilds, I have created an appropriate set of commands.
I defined a new panel of commands, pguilds , that is defined as follows:
PANEL pguilds VERSION OF default CR CR BUTTON guildcmd, "Do this: ", "Guild action", doGuildOperation DROPDOWN guildop, guildOps, join LABEL "" DROPDOWN guildsel, guildnames, 0
As it stands, it is derived from the default panel. We added two drop-down lists ( DROPDOWN control ). This is a new control that has been introduced in version 6.0.2 of DimensioneX, and it works like this (we see the guildop list first):
3 the drop-down list
The first ID, guildop is the dropdwn itself.
We don't have to worry about this ID until we have to read the player's input.
Second, we find a name of a SET, guildOps. This is fundamental because it should contain all the available choices, that is, all the commands that I am setting up for the users.
4 il set comandi
The guildOps command set could have been defined in the SETS section, but I found it more convenient to create it inside the onStart event, which is called automatically at the game's start. If you go and check it out, you will find out that this event's code is in the file named underworld.dxw:
guildOps = NewSet("0new=Start new guild, 1edt_logo=Change logo, 2edt_web=Change website, 3del=Delete my guild, 4ban=Ban a member, 5-=------(all users)------, join=Join this guild:, leave=Leave this guild:")
A SET is an associative array, and the NewSet function allows me to define it via a simple syntax: Elements are separated by commas and are key=value pairs.
The key is a unique identifier inside the set, I have made some of them starting with a number so to have a well defined ordering. The value is a string which is what the user will actually see in the drop-down list. The key is what I will have to check to discover what the user has chosen.
now, thanks to the DROPDOWN control this SET is automatically turned into a dropdown list.
5 the guilds set
Coming back to the pguilds panel, you see that there is a second drop-down control there. This is because for example, if the user wants to join a guild, he has to choose which one.
So I put a second drop-down, with the guilds' names. Here you see the used SET is called guildnames.
guildnames is a set that contains the guild names. I decided to use as keys the names of the guild founders, since each person can start no more than one guild a time. In this way it gets easy to see, for any given person, if he/she owns a guild.
guildnames is created this way:
guildnames = NewSet()
which is called by the onStart event.
For the sharpest programmers: This instruction can be found in the commons.dxl file in the common_onStart Sub.
This contains all the initialisation code which is common to the several areas of Underworld. The guilds are valid for all areas in fact, while the operations on the guilds are allowed only in the castle area, that is why the initialisations of these sets are done in different places in the code. This however is not of much importance.
The above mentioned instruction creates and empty set.
The guilds application, which we will examine straight away (but we can already say that code lays is in the doGuildOperation() event), simply adds new guild names to the set when the user requests so.
6 the persistence
To avoid that guilds data, such as their names stored in guildnames, vanish when the game or is restarted we must save on disk these information.
To do this, in the procedure which actually represents the guilds application: doGuildOperation() - you will find it inside underworld.dxw- we use the following:
This saveSetting saves the whole set guildnames in a setting related to the game's context, which we will load back once the game is restarted. Please not that in the local onStart event we have got:
Call LoadContext() ' Reads game saved status from disk
Which is a call to a single function which is designed to load, at the game start, these context values with a number of getSetting. These will reconstruct the exact guilds situation as it was before game restart.
It is interesting to notice that saveSetting with the guilds data is performed only when necessary, that is when a guild operation is performed. The saveSetting is not performed a regular intervals in time. This is because saveSetting is a slow operation and causes performance degradation in the game, which is what we want to avoid.
7 the guilds application
The guilds management application is contained in a single procedure which handles the possible operations. This is done in the single event doGuildOperation() which you find in underworld.dxw.
This event is called (just see the pguilds panel) by menas of the guildcmd button. This is because - at least in the version we used - it is not enough to select a new value on a drop-down to make the form to be submitted. This can be made only via pressing a button, so that's why that button was inserted..
Finally, let's see the code:
EVENT doGuildOperation 'Speak guildOps(input("guildOp")) Dim tmp = $AGENT.name If Int(tmp) > 0 tmp = "_" + tmp ' fix for number nicks End_If If input("guildOp") = "0new" If input("txtBox") <> "" If guildnames(tmp) <> null Speak guilford,$AGENT,"You already own a guild, sir." Return End_If If $AGENT.Experience < $AGENT.mxe Speak guilford,$AGENT,"To found a guild requires more Experience, sir. Come back later." Return End_If Dim s = guildSubscribed($AGENT) If s <> null Speak guilford,$AGENT,"You have to leave " + guildnames(s) + " first." Return End_If SetAdd guildnames,tmp,input("txtBox") saveSetting "ctx_guildnames",guildnames Else Speak guilford,$AGENT,"How do you want it to be named? Write it down." Return End_If End_If If input("guildOp") = "3del" If guildnames(tmp) = null Speak guilford,$AGENT,"You don't own any Guild, sir." Return End_If If input("txtBox") <> "YES" Speak guilford,$AGENT,"Are you sure? Type YES and redo." Else Speak guilford,$AGENT,"Ok, no more " + guildnames($AGENT.name) SetRemove guildnames,tmp SetRemove guildlogos,tmp SetRemove guildwebs,tmp SetRemove guildkills,tmp SetRemove guildsubscribers,tmp End_If End_If If input("guildOp") = "1edt_logo" If guildnames(tmp) = null Speak guilford,$AGENT,"You don't own any guild, sir." Return End_If If input("txtBox") = "" Speak guilford,$AGENT,"Type logo URL and redo." Else Speak guilford,$AGENT,"Ok, sir. New logo for your guild!" SetAdd guildlogos,tmp,input("txtBox") End_If End_If If input("guildOp") = "2edt_web" If guildnames(tmp) = null Speak guilford,$AGENT,"You don't own any guild, sir." Return End_If If input("txtBox") = "" Speak guilford,$AGENT,"Type web page's URL and redo." Else Speak guilford,$AGENT,"Ok, " + $AGENT.name + ". Make that page to describe you guild's mission." SetAdd guildwebs,tmp,input("txtBox") End_If End_If If input("guildOp") = "4ban" If guildnames(tmp) = null Speak guilford,$AGENT,"You don't own any guild, sir." Return End_If If input("txtBox") = "" Speak guilford,$AGENT,"Type the name of the member and redo." Else If Not(GuildUnsubscribe2(tmp,input("txtBox"))) Speak guilford,$AGENT,"-" + input("txtBox") + "- is not a member of your guild, sir." Else Speak guilford,$AGENT,"Done, sir." End_If End_If End_If If input("guildOp") = "join" If guildnames(tmp) <> null Speak guilford,$AGENT,"You cannot join a guild if you own one." Else Dim s = guildSubscribed($AGENT) If s <> null Speak guilford,$AGENT,"You have to leave " + guildnames(s) + " first." Return End_If Call GuildSubscribe(input("guildsel"),$AGENT) Speak guilford,$AGENT,"You now belong to " + guildnames(input("guildsel")) End_If End_If If input("guildOp") = "leave" If guildnames(tmp) <> null Speak guilford,$AGENT,"You cannot leave a guild if you own one, sir." Else Speak guilford,$AGENT,GuildUnsubscribe(input("guildsel"),$AGENT) $AGENT.guild = null End_If End_If If input("guildOp") = "5-" Return End_If Call guildroom.onReceive saveSetting "ctx_guildnames",guildnames saveSetting "ctx_guildlogos",guildlogos saveSetting "ctx_guildsubscribers",guildsubscribers saveSetting "ctx_guildwebs",guildwebs saveSetting "ctx_guildkills",guildkills END_EVENT
Here we notice how a drop-down control works. The choice on the control called guildOp comes to the server in a pre-defined set named input, which contains all data sent by the commands panel. The keys of the input set are IDs of the controls of the panel, and their values are the entered values - in the case of the dropdown, the key of the chosen option -.
Still about the drop-down, the value that I will receive in input, is not what the user has seen (description) but the code (key) I specified in the set defining possible options. Go back and see section 4 above for a reference.
8 management of SET objects
To this point the guild management is fairly simple. To each command we have an IF branch and a sequence of operations to be executed, which are not quite complex.
Be careful: All data about guilds are in SETs whose keys are the names of the guild owners.
In the DimensioneX version we used (6.0.2) we cannot add a new element in a set this way:
myset("newkey") = "newvalue" 'will not work
but we must use the SetAdd instruction as you see in the source code. It is possible that this changes in the upcoming releases, but if you modify the code you have to remember about that because by using the above syntax you won't get errors nor any useful result, and you will be wondering why.
In a summary, the SETs used by guilds system are these ones (you will find them all in LoadContext() that is defined in commons.dxl)
- Names of the guilds
- Logos of the guilds (URL)
- Semicolon ";" separated list of the names of the subscribers of each guild
- web pages of each guild (URL)
- killed enemies for each guild
The last one, guildkills, gets updated at each killed character and is stored bymeans of saveSetting each 4 minutes by means of careful use of the onTick event.
Please note that this update is based on the guild property that is set at the player's joining, with a check to see if the guilds he subscribed to is still existing - see the onNew() event.
9 mostrare i dati di gilda
Guilds data are displayed by means of the little function: getGuildBox(), defined in commons.dxl. This function requires you specify the name of the guild owner and if you want ot not to see the list of the subscribers with killed enemies data.
Members: " + Replace(guildsubscribers(owner),";",", ") txt = txt + "
Kills count: " + guildkills(owner) End_If Return txt End_Function
This function is repeatedly called with a loop each time we enter in the guilds room, so that all guilds are displayed:
EVENT guildroom.onReceive Dim txt="This the room of the guards' captain. He knows about all existing Guilds."txt = txt + "
For i = 1 To SetLen(guildnames)
owner = SetKey(guildnames,i)
txt = txt + "
- " + getGuildBox(owner,true) Next txt = txt + "
guildroom.description = txt END_EVENT
so that when I enter there I always see the updated situation.
Furthermore, the function is called also by the Info command button, which returns information about the player himself (find it in battlesystem.dxl).
Sub doCheckup() Dim item Dim name Dim s,guild s = guildSubscribed($AGENT) If s=null guild = "Guild: None." Else guild = getGuildBox(s,false) End_If Print guild ...
First of all, by means of the guildSubscribed() function, this one checks to which guild you are subscribed to then it calls getGuildBox to print guild data out.
The getGuildBox itself is used in the onLook EVENT to provide this information about you when somebody looks at you.
The guilds system is a tiny application we built into Underworld that demonstrates how to use the following features of DimensioneX:
- drop-down lists
moreover, it is perfectly compatible with the multi-area structure of the game, so it can be applied to all contexts. It would be possible, at this point, to add more elements to make the guild management more interesting for gameplay.
If you have comments or questions, you can either use the DISCUSSION tab on this page, or to post on our [Forum].