HowtoAddASpellToTheDatabase
Managing Magic Ways
Most of the magic ways configuration is hardcoded into the engine but the names of all magic ways are stored in the database table ways. The columns of this table are described on the page WaysTable. You can easily rename magic ways or delete them but adding more than six magic ways requires modifying the PlaneShift source code. This is beyond the scope of this document. Nonetheless here are some hints how to get started if you want to have more than six ways of magic:
- Update number of glyph ways GLYPH_WAYS in src/common/util/psconst.h
- Define new PSITEMSTATS_SLOT_? for your way in src/server/bulkobjects/psitemstats.h
- Update src/server/bulkobjects/psitemstats.cpp to map this new slot to a database identifier.
- Update src/server/spellmanager.cpp to handle the new slot and assign an internal magic way id to it.
- Update src/client/gui/pawsglyphwindow.cpp to handle the new way and map it to a gui element.
- Update the gui XML file data/gui/glyph.xml to display your new way.
Adding Magic Ways
If you populated the database the way it is described in the Compile Guide you should already have the standard magic ways configured. In case you want to do it on your own you should have a look at src/server/database/mysql/ways.sql. You can edit this file and then just recreate the table by importing it into the database.
$ mysql -u <user> -p <db> mysql> drop table ways; mysql> source ways.sql;
However before you start customizing the names of the magic ways you should think of a mapping which maps your new names to the PS internal magic way db-identifiers. PS knows the following six magic way database identifiers: CRYSTAL, AZURE, RED, DARK, BROWN and BLUE. The mapping will be required when you want to add glyphs to the database or wipe out a magic way.
Modifying Magic Ways
Renaming magic ways is straight forward and can be done by editing the ways.sql file - like described in the last section - or by using a standard mysql database client like the command line tool mysql or the mysqlmanager. Here is an example which renames the magic way with id 1 to the name MyMagicWay:
$ mysql -u <user> -p <db> mysql> UPDATE ways SET name='MyMagicWay' WHERE id=1;
Deleting a magic way requires more efforts as the PS database schema does not do proper foreign key referencing. This is because many tables use the MySQL MyISAM engine which does not support this feature. Therefore you have to make sure to properly cleanup all entries from different tables. To completly wipe out a magic way with all of its glyphs and spells you have to:
- Delete the magic way itself from table ways.
- Delete all spells which belong to the magic way from spells.
- Delete all instances of the deleted spells from player_spells.
- Delete all spell glyphs entries which reference a deleted spell from spell_glyphs.
- Delete all glyphs which belong to the magic way you want to wipe out from item_stats.
- Delete all glyph item instances from item_instances.
- Optionally delete obsolete math scripts from math_scripts.
- Optionally delete obsolete progression events from progression_events.
Suppose you would like to delete the azure way which has the database identifier AZURE and the primary key 2. In SQL this would look like:
$ mysql -u <user> -p <db>
## Delete all item instances which belong to the azure way (db identifier = 'AZURE').
mysql> DELETE FROM item_instances WHERE item_stats_id_standard IN
(SELECT id FROM item_stats WHERE valid_slots LIKE '%AZURE%');
## Delete all items which belong to the azure way (db identifier = 'AZURE').
mysql> DELETE FROM item_stats WHERE valid_slots LIKE '%AZURE%';
## Delete all spell glyphs which belong to the azure way (primary key = 2).
mysql> DELETE FROM spell_glyphs WHERE spell_id IN (SELECT id FROM spells WHERE way_id=2);
## Delete all instances of the spells which belong to the azure way (primarky key = 2).
mysql> DELETE FROM player_spells WHERE spell_id IN (SELECT id FROM spells WHERE way_id=2);
## Delete all spells which belong to the azure way (primary key = 2).
mysql> DELETE FROM spells WHERE way_id=2;
## Delete the azure way itself (primary key = 2).
mysql> DELETE FROM ways WHERE id=2;
Managing Spells
Spell management is paritioned into the following tables:
| Table | Description |
|---|---|
| spells | The spells themselves. |
| spell_glyphs | The required glyphs for each spell. |
| item_stats | The glyphs themselves. |
| item_instances | Instances of the glyphs a player has. |
| player_spells | Instances of the spells a player has researched. |
| math_scripts | Spell parameters like range,.... |
| progression_events | What the spell does (result) and text messages. |
| ways | The names of the magic ways. |
Adding a Spell
Create Glyphs
To create a new spell you should first create the required glyphs. In PS a glyph is defined as a normal item and therefore stored in the table item_stats along with all other items. What distinguishes a glyph from a normal item is its flag GLYPH and the valid_slots field which defines its magic way. From an item's point of view a magic way is just another slot like for examle ARMS, TORSO, HELM,... and so on. For each magic way PS has its own unique slot name - which are: CRYSTAL, AZURE, RED, DARK, BROWN and BLUE. To define your own glyphs you should have a look at the file src/server/database/mysql/item_stats.sql and watch out for entries whose flags field is set to GLYPH. Experiment by altering these entries and reimport the item_stats table after editing.
Create a Spell
Now that you have configured your glyphs, you can add a new spell. Each spell belongs to one of the magic ways and to add a new spell you need to know the primary key (id) of the magic way from the ways table. The basic parameters of each spell are stored in the table spells. As an example you can look at the spells defined in src/server/database/mysql/spells.sql. Modify this file and reimport it into the database.
The most important parameters of this table are the name of the spell, the magic way, the offensive flag, the progression event and the target type. The name of the spell is important as it is also the name of the math script you will have to add in one of the next steps. The magic way of course defines the spell's way and has to match one of the ways configured in the table ways. The progression event defines what the spell does (result) and all the messages which are send to the clients. The offensive flag controls if you can cast the spell on friends/yourself - you cannot cast an offensive flag on yourself as you may not attack yourself. The actual valid targets are set in the target_type column which allows you to explicitly define all valid target types. Be aware that you can create a non useable spell if you define only friends or yourself as target types and set the spell to offensive mode.
Assign Glyphs to the Spell
After creating your spell you have to define which glyphs are required to cast or research the spell. This is done in the table spell_glyphs which only consists of three columns: The spell id from table spells, the glyph's item id from table item_stats and the slot (position) the glyph has to be in when the spell is researched. Again you can just edit and reimport the file src/server/database/mysql/spell_glyphs.sql or insert the glyph dependencies using SQL insert statements.
Create the Math Script
For each spell a math script is required which defines basic parameters of the spell. All the math scripts are stored in the table math_scripts. The name of the math script for your new spell has to match the name of the spell. You should have a look at the examples in src/server/database/mysql/math_scripts.sql to see what's possible. In PS 0.4.03 the spell system supports the following parameters. A current parameter list can be extracted from src/server/bulkobjects/psspell.cpp.
| Parameter | Description |
|---|---|
| Range | |
| Duration | |
| CastingDuration | |
| PowerLevel | |
| AntiMagic | |
| AffectRange | |
| AffectAngle | |
| AffectTypes | |
| ProgressionDelay | |
| UseSaveThrow | |
| WaySkill | |
| Param# | Custom parameters (# = number). |
Create a Progression Event
To make the spell actually do something it needs a progression event. All progression events are stored in the table progression_events. The name of the progression event has to match the entry progression_event of the table spells. Have a look at the examples in src/database/mysql/progression_events.sql. A progression event basically defines the result of the spell and the messages which are send to the clients - like "You have been healed".
Deleting a Spell
To delete a spell you have to do the following steps:
- Delete the spell from spells.
- Delete all instances of the deleted spell from player_spells.
- Delete all spell glyphs entries which reference the deleted spell from spell_glyphs.
- Optionally delete obsolete math scripts from math_scripts.
- Optionally delete obsolete progression events from progression_events.
Suppose you want to delete the spell with spell id (primary key) 1 the SQL code would look like:
$ mysql -u <user> -p <db> ## Delete all instances of the spell (primarky key = 1). mysql> DELETE FROM player_spells WHERE spell_id=1; ## Delete all spell glyphs which belong to the spell (primary key = 1). mysql> DELETE FROM spell_glyphs WHERE spell_id=1; ## Delete the spell (primary key = 1). mysql> DELETE FROM spells WHERE way_id=1;