Revision as of 17:36, 18 November 2010

NOTE: following the tutorials will be much easier if you do them in order.
NOTE2: These tutorials are for the developmental ( SVN ) version

Part 1

This section of the tutorial covers initial set up of the recommended directory structure.

The RPG module detects the available games by scanning data/rpg/games for cfg files, these are stored in a list and executed when a game is chosen. If a prior game is in progress, it's status will be irretrievably lost.

So let us start by creating our own game, we will name it tutorial. We will start of by creating a file named tutorial.cfg inside data/rpg/games. If you want you may try to load it now (it won't succeed).

Next up, you should execute the contents of data/rpg/games/common, while not strictly necessary these default definitions will prove useful. At this stage our tutorial.cfg should look like this.

 loopfiles f data/rpg/games/common cfg [ exec (concatword "data/rpg/games/common/" $f ".cfg") ]

(see the cubescript page for a full explanation of the commands)

Next up, we'll define the player. So create a directory inside data/rpg/games named tutorial, and create a file named player.cfg inside it. Then add the following inside it.

 r_char_new
 r_char_mdl ogre

We now need to alter tutorial.cfg to load these new assets. we will also pre-emptively add the command to load the first map, which we shall name tutorial. tutorial.cfg should now look like this

 loopfiles f data/rpg/games/common cfg [ exec (concatword "data/rpg/games/common/" $f ".cfg") ]
 loopfiles f data/rpg/games/tutorial cfg [ exec (concatword "data/rpg/games/tutorial/" $f ".cfg") ]
 
 map tutorial

Now just launch sandbox and load your game via the menu and type /savemap tutorial; you are done.

Congratulations, you have just started your own game using the RPG module.

Addendum

The recommended order of execution is as follows, paths are given relevant to your game's directory.

• common (../common)
• particles (particles)
• statuses (statuses)
• items (items)
• ammo (ammo)
• weapons (weapons) - required for the subset that needs the above ammotypes
• recipes (recipes)
• root (.)
  • player - this should be the FIRST creature definition
  • variables
  • tips
• factions
• creatures
• objects
• cutscenes
• maps

Part 2

This section of the tutorial covers creating an item, a companion status effect, equipping it, as well as some script related stuff.
The item in question will be a "helm of brilliance" (for sake of argument it only glows brightly).

Before we get started, we will need 3 more directories than we did for the prior part, so we should create them first and add them to tutorial.cfg before continuing. The directories are to be called "items", "statuses" and "maps". your tutorial.cfg should look like this afterwards; new lines are commented with a *

 loopfiles f data/rpg/games/common cfg [ exec (concatword "data/rpg/games/common/" $f ".cfg") ]
 loopfiles f data/rpg/games/tutorial/statuses cfg [ exec (concatword "data/rpg/games/tutorial/statuses/" $f ".cfg") ] //*
 loopfiles f data/rpg/games/tutorial/items cfg [ exec (concatword "data/rpg/games/tutorial/items/" $f ".cfg") ] //*
 loopfiles f data/rpg/games/tutorial cfg [ exec (concatword "data/rpg/games/tutorial/" $f ".cfg") ]
 loopfiles f data/rpg/games/tutorial/maps cfg [ exec (concatword "data/rpg/games/tutorial/maps/" $f ".cfg") ] //*
 
 map tutorial

Also before we get started, we should create a spawn point in our map, so load up your game (and ignore any warnings should they exist). Enter editmode (F1 in RPG mode) place your cursor where you want the entity and enter (press T) /newent spawn. The editmode helper should say it has a tag of 0. Now just save your map so we can get started.

First off we should create the status group, so create a file named "helm of brilliance.cfg" inside data/rpg/games/tutorial/statuses. Then add the following into it. We will be using the alias "status_helm_of_brilliance" to refer to this status effect.

 status_helm_of_brilliance = (r_status_new)
 
 r_status_name "Helm of Brilliance"
 r_status_description "The helm shines brilliantly and pierces the darkness."
 
 r_status_addlight .75 .75 .5 32

next up we will create another file named "helm of brilliance.cfg", but this time inside data/rpg/games/tutorial/items. We will be using the alias "helm_of_brilliance" to refer to it.
The next bit of code may require some explanation. Items can be be used 3 different ways, it can be consumed/used, it can be equipped as armour, or wielded as a weapon. In our case we want to use the second type. You might've also noticed "genericpickupscript", this is a helpful dummy defined inside data/rpg/games/common, which contains a generic pickup script. We also use some of the constants defined inside data/rpg/game.cfg

 helm_of_brilliance = (r_item_new)
 r_item_name "Helm of Brilliance"
 r_item_description "The helmet is white and radiates a yellow coloured light. "
 r_item_script $genericpickupscript
 r_item_worth 500
 r_item_weight 8
 
 r_item_use_new_armour //the first usetype is for an armour equip
 r_item_use_status $status_helm_of_brilliance
 r_item_use_slots $SLOT_HEAD
 r_item_use_skill -1 //reserved type, light no longer depends on our skills

We are almost there, we just have one more file to create. We simply have to associate the spawn entity with the item on that map, and this is done via mapscripts. We will now create our first one. since we'll be using the tutorial map, create a file named tutorial.cfg inside data/rpg/games/tutorial/maps. Enter the following.

 r_registermap tutorial (r_mapscript_new)
 r_mapscript_load [
   r_spawn_item self 0 @helm_of_brilliance
 ]

We are done. You have successfully created a helm of brilliance and added it to the game.
Just load up your map, walk up to the helmet and press E (to pick it up). Press TAB and it should show in your inventory. You can equip it here. Enjoy!

Addendum

Spawning with the item

We could've altered the player's spawn script instead of created a load script for the map. The resulting player.cfg is shown below. The example below would also equip the item automatically for you.

 r_char_new
 r_char_mdl ogre
 r_char_script (r_script_new)
 
 r_script_spawn [
   r_additem self @helm_of_brilliance 1
   r_equip self @helm_of_brilliance 0
 ]

Several effects

You might think it's odd that a helmet only emits light, but provides no protection. Just add the following snipper onto the end of the status effect file to add 5% resistance to all attack types.

 loop i $ATTACK_MAX [
   r_status_addgeneric (+ $STATUS_FIRE_R $i) 5
 ]

Skills and magnitude

Skills determine how effective spells and such are. Unfortunately it is 100% random, which in the case of our helmet would cause significant flickering. type -1 always returns 1, unlike the other types. This sort of an unexpected usecase, but one we hope to have corrected in the future, so that such flicker will not exist.

Part 3