Adding Game Entities (Armor, Spells etc.)

Description

After hours and hours of staring at the xml files and browsing restless through the georges editor, i finally could shed some light into the mysteries of entity creation in Ryzom Core. There is still much to learn but this is a good point to start to share my knowledge i gathered so far.

So what we're going to do is creating an armor item including a crafting plan and two spells (Heal & Dmg) plus some more spell credits. We're going to put them on both server (shard) and client. Finally, we are adding them to some corresponding merchants & trainer (NPC).

Note 1: For the sake of simplicity in this guide I oriented myself at the old spells and armor. Of Course, the goal of Ryzom Core is not to rebuild the original Ryzom. But in my opinion it will take some time till we have e.g. some truly new spells as this also relies heavily on source code additions. Until then it should be ok if we create some more samples to get to known with the whole process.

Note 2: Personally i think the current georges editor has much potential, but most times im kind of overwhelmed by the masses of editable informations.
So i switched to just open the actual xml files and edit them. I decided to do it for this guide as well which also saves me from making a lot of screenshots :) But of course you are welcome to do it all in the offical Nel tool!

If you don't like to read, videos are available 

• Create armor, craft plan, implement

• Add item to a merchant

Prerequisites

Here is a small list with stuff you should have ready for things to work.

• Get the source
  Look here for more information

Note: For windows there are some prebuild binaries for everything (client, server, nel tools, ryzom tools). Look at Downloads for Windows to find out more.

• Client / Server
  Well this should be clear but of course you need a working client to test the additions and a working server with access to it as we have to add files on it. There are a bunch of tutorials in the wiki for the plattform of your choice. E.g.:

  • Linux

  • Mac OS X

  • Windows

• Char with admin rights
  Create a character on your server and grant it some privileges. 
  This can be done by using the EGS (Entity Game Service - part of the server) command "setPriv 1 :DEV:" when the corresponding user is logged into the Client, or by directly altering the corresponding table entry for your character in the mysql database on the server.

Note: If you have more than one character on your server you need to change the EGS command to "setPriv x :DEV:" where x is the id of the char found in the mysql database

• NeL tool "make_sheet_id" 
  This tool is needed to create the sheet_id.bin file which is residing in $RYZOM_HOME/code/ryzom/common/data_leveldesign/leveldesign/Game_elem. Therefore build it and make it ready for use. It can be found in $RYZOM_HOME/code/nel/tools/misc/make_sheet_id.
  Use it with the following syntax to build your sheet_id.bin (also produce sheets.txt) :

make_sheet_id_r -oL:/leveldesign/game_elem/sheet_id.bin L:/leveldesign/game_elem L:/leveldesign/game_element L:/leveldesign/world

Note: To get working make_sheet_id tool you need set allowed extensions or simply just delete or comment ExtensionsAllowed = { "sample_config" }; line in $RYZOM_HOME/code/nel/tools/misc/make_sheet_id.cfg

Linux

• Ryzom tool "sheets_packer"

Linux

• Ryzom assets
  Its really nice to have the ryzom media assets available. E.g. the Interfaces directory contains all the icons for spells and stuff. You could search for them online at http://media.ryzom.com/ but having them locally is much faster. Bear in mind that all assets, if extracted, are like 11GB in 26k files.

• bnps
  For creating armor its nice to have some of the bnps available unpacked to look for nice shapes you want to use. Download the Open Ryzom Client extract it and look into the data directory. There you will find all the .bnp files. Use the NeL tool bnp_make to unpack the files. The easiest way to do so is to copy the desired bnp and the executable in a directory and using following command. This will create a directory with the name of the file and unpack all contents there.

bnp_make /u desired_bnp.bnp

• sbrick_words_en.txt / skill_words_en.txt / item_words_en.txt

  It comes in handy if you have these files open. The first three can be found in the $RYZOM_HOME/code/ryzom/server/data_shard/language directory. They are needed later to find the correct skill families and item names (more on that below).

   

•  sheets.txt
  This file gets created if you repack your sheets with the mentioned sheets_packer tool. It contains a human readable overview of the contents of the sheet_id.bin and can be used to find out correct file naming as we're orienting on the original ryzom file scheme. It lies in the same directory as the sheet_id.bin.

Adding Armor

File naming constraints 

Each craftable item needs a .sitem file which defines the characteristics of the item and a .sbrick file which defines the crafting plan for the item (eg which material is used). As kaetemi already stated in his armor example: "Craftable items MUST be prefixed with "ic", bricks for crafting MUST be prefixed with "bc"". As we orient ourselves to the ryzom naming scheme there are some more rules to learn. But more on this in the next paragraph

File extension, Skill Families, Icons etc.

• To get correct .sitem file naming we are looking into the item_words_en.txt (in the $RYZOM_HOME/code/ryzom/server/data_shard/language directory)

• To get correct .sbrick file naming we are looking into the sbrick_words_en.txt (in the $RYZOM_HOME/code/ryzom/server/data_shard/language directory)

• We can double check with the sheets.txt if the file names are appearing there (in the $RYZOM_HOME/code/ryzom/common/data_leveldesign/leveldesign/Game_elem directory)

Below is a table with some examples for the naming scheme for matis armor .sitems and there corresponding .sbricks . There is a lot more to discover if you skim through these files but this should be sufficent to get the idea.

For the crafting plans we need to know the corresponding skills involved

• To get the correct skill family we are looking into skill_words_en.txt (in the $RYZOM_HOME/code/ryzom/server/data_shard/language directory)

Below is a table with some example skills we are going to use and there skill family. This should give you an sufficent idea.

Throughout the existing .sbricks i found they always use the master skill, although there are familyIds for e.g. the expert skill. Im adapting this remembering that even in original ryzom they got this strange info message that you can`t gain any more XP in the master skill lvl when killing low mobs even though you not yet reached that master skill.

All items, skills and plans etc. need an icon to show ingame. Here is a short list, find others in the ryzom_assets:

Creating Armor SItem

So first we are looking for some nice armor to add. For this step you need to unpack the characters_shapes.bnp. Now skim through the .shape files with the Nel object viewer or the new object_viewer_qt until you find a pleasing one. If you want the shape to have textures provide them from the ryzom assets. They can be found in e.g. $ASSETS_PATH/Stuff/Matis/Agents/_textures/Actors

Linux - extract all client ".bnp" files

Open

File view with object viever qt (ovqt)

As my toon is matis and female im choosing MA_HOF_armor00_gilet.shape (MA = Matis; HOF = Homin Female). The male shape would be MA_HOM_armor00_gilet.shape (can be found in $CLIENT_HOME/data/characters_shapes/ corresponding to characters_shapes.bnp)

Ok so now its time to actually write the georges files.

Switch over to your leveldesign directory to the corresponding sitem armor folder. 

Linux

There you'll find the already provided matis light armor boots file

icmalb.sitem

We are lazy and just copy this file. Now rename it according to your desired item (see filenaming above). As i want to have a matis light vest i'll name it icmalv.sitem

Open it and you should see something like this:

As you can see there's also a parent defined which declares some standard matis armor values. We dont need it at the moment but if you want to have a look at it you'll find the file at leveldesign/game_element/sitem/armor/_parent/matis

So now we need to change the values to match a vest (already modified file provided below) :

• change the "EquipmentSlot" from Value="Feet" to Value="Chest" (line 10)

• change the "CraftPlan" to "bcmaea11.sbrick". This is the needed corresponding sbrick file i mentioned earlier. We will create it later. (line 13) 

• change "shape" and "shape_female" to the shape names we found out earlier (MA_HOM_armor00_gilet.shape and MA_HOF_armor00_gilet.shape) (lines 16 ; 17)

• change "icon" to "AR_gilet.tga" (see icons above) (line 19)

• if you like you can add another "ATOM" below "icon background" in the "3D" "STRUCT". Name it "color" and give it the value "White" (Black, Beige, Green, Red, Turquoise, Blue, Violet are also available) (between lines 20-21)

• save the file which should now look something like this:

Creating Armor SBrick

So far so good! Now we need to add the brick for crafting. Have a look into the sbrick folder

Linux

Remember, we changed bcmaea07.sbrick into bcmaea11.sbrick on the .stiem file (see above).

So the craft plan for icmalv.sitem will be bcmaea11.sbrick. We will start from bcmaea07.sbrick to build bcmaea11.sbrick

Again we are going to change it now to resemble a vest craft plan

• change IndexInFamily to 11 as this is the 11th item in the BCMAEA family (line 6)

• change Skill to SCALVEM (Master Light Vest Crafting) (line 10)

• change icon to AR_gilet.tga (line 15)

• change "Crafted Item" to icmalv.sitem (line 24)

• for simplicity i shortened the raw material list :)

Finally your file should look something like this:

Make it available on server and client

Open

Well, we have come a long way :) Now its time to test it!

• Build the sheet_id.bin with the make_sheet_id tool and copy it to the user dir in your game client dir

Linux - make_sheet

• Create new .packed_sheets files to send to client.

Linux - sheets_packer

• Remove .packed_sheets from the server. 

Linux

• Restart server

Linux

Make sure the two files we created are existing in the correct dir in your leveldesign dir and that they contain the content i explained before

start your client and let him connect to your server

when ingame select your char and type the following command into the chat

/a createItemInBag icmalv.sitem 1 25

you should now have the new item in your inventory, congratz :D

Tutorial Videos

Part 1

Part 2

Part 3

Add armor to merchant

Let's say we want to add our previously created vest to the existing light armor mechant.

Edit $RYZOM_HOME/code/ryzom/common/data_leveldesign/primitives/newbieland/urban_newbieland.primitive and search for :

That's the list of items, the merchant is already selling.

We will add our vest to the end of the list:

<STRING>item : icmalv.sitem 10</STRING>

The number following the sitem is the level of the item.

• Save the file and place it on your server