Platinum Arts Sandbox Free 3D Game Maker - User contributions [en]

PAS to Blender

2012-11-18T16:08:48Z

Kddekadenz:

'''Exporting a PAS map to Blender'''

1.) Press T and type /writeobj modelname

2.) Close Sandbox - if you use the standalone version, you can find the model as .obj in your Sandbox main directory

3.) Import the .obj in Blender

[[File:Pas_to_blender4.jpg]]

4.) Switch to textured view

[[File:Pas_to_blender2.jpg]]

5.) Merge the textures into the blend

[[File:Pas_to_blender3.jpg]]

6.) Save the blend

optionally: export the textures to the same folder

[[File:Pas_to_blender1.jpg]]

PAS to Blender

2012-11-10T18:26:52Z

Kddekadenz: Created page with ''''Exporting a PAS map to Blender''' 1.) Press T and type /writeobj modelname 2.) Close Sandbox - if you use the standalone version, you can find the model as .obj in your Sand…'

'''Exporting a PAS map to Blender'''

1.) Press T and type /writeobj modelname

2.) Close Sandbox - if you use the standalone version, you can find the model as .obj in your Sandbox main directory

3.) Import the .obj in Blender

4.) Switch to textured view

5.) Merge the textures into the blend

6.) Save the blend

optionally: export the textures to the same folder

Gonna add some pics soon ;)

Tutorials List

2012-11-10T18:21:07Z

Kddekadenz: /* Models and Sandbox */

A list of tutorials created and edited by our contributors.
Contribute by improving the tutorials and creating tutorials for the red links
== Getting, Installing and opening Sandbox ==

* [[Downloading Sandbox]]
* [[Installing Sandbox]]
* [[Running Sandbox]]
* [[development|Obtaining the development version]]

== Modules ==

* [[FPS|FPS - First Person Shooter (default)]]
* [[SSP|SSP - Side Scrolling Platformer]]
* [[RPG|RPG - Role Playing Game]]
** [[RPG tutorial|RPG Tutorial]]
* [[MovieCube|MovieCube - Machinima Tool]]
* [[Vehicle Simulator]]

== Learning the editor basics ==

* [[Map Editing Basics]]
* [[How to change textures in your map]]
* [[How to place 3D grass]]
* [[How to add lava, water, glass and other materials to your map]]
* [[How to make ramps, bridges, and angles]]
* [[How to make invisible boundaries]]
* [[Tips on making a good map]]
* [[Gridwork]]

=== Buildings ===

* [[How to make sloped roofs]]
* [[How to make secret doors, walls & floors]]
* [[How to make 1-way windows only you can see out of]]
* [[How to make 1-way doors]]
* [[How to create a hollow tower/tube]]
* [[How to make stairs you could walk up]]
* [[How to create set of glass stairs]]
* [[How to make a TV]]
* [[How to make various window shapes]]
* [[How to create a spiral staircase]]
* [[How to make a pyramid/four-sided sloped roof]]

=== Terrain editing ===

* [[How to create mountains, ponds, and oceans]]
* [[How to transfer parts of a map to a new one]]
* [[How to make a forest]]
* [[How to make a cave]]
* [[How to make a realistic river]]
* [[How to make a swimming pool]]
* [[How to make a fountain]]
* [[How to create smooth curvy pathways]]
* [[How to create fields with flower patches]]
* [[How to create a camp fire and fireplace]]
* [[How to make a bumpy road]]
* [[How to make various types of fences]]
* [[How to make a nice waterfall]]
* [[How to edit terrain properly]]
* [[How to fix bad terrain or geometry errors]]
* [[How to make railings]]
* [[Texture Blending]]

=== Advanced Editor Techniques===

* [[How to create a slide]]
* [[How to create a trampoline]]
* [[How to create electric fences]]
* [[How to make a sphere shapes in 'edit mode']]
* [[How to make curved shapes in 'edit mode']]
* [[How to create curved glass]]
* [[How to create climbable ladders and vertical walls]]
* [[How to make an endless slide]]
* [[How to create lens flares]]
* [[How to make a snowman]]
* [[How to make a boat]]
* [[How to create warp speed tunnels]]
* [[How to create hidden teleports]]
* [[How to create spinning palm trees]]
* [[How to change gravity]]

== Lighting and Particle effects ==

* [[How to add various lighting]]
* [[Lighting|How to light a map properly]]
* [[Tips to make a night time map]]
* [[Tips to make a morning map]]
* [[Tips to make a sunset map]]
* [[How to add particle effects]]
* [[How to create snow or rain]]
* [[How to put fog to a map]]

== Models and Sandbox ==

* [[Blender to Sandbox]]
* [[Wings3D to Sandbox flash tutorials]]
* [[Mapmodels|Loading and adding mapmodels]]
** [[Importing .OBJ files]]
* [[How to add new models]]
* [[PAS to Blender]]

== Textures ==
* [[Adding custom textures to a new map]]
* [[Adding custom textures with normal maps]]

== Scripting/Trigger tutorials ==

=== Menu Editing - Cubescript ===
* [[Menu Editing|How to modify the menu]]
* [[Cubescript]]
* [[Creating easy spells]]
* [[Removing Editmode]]
* [[Adding Custom Skyboxes]]
=== Maptitle and authors ===
* [[How to add map title and author]]
* [[How to change color of text in maps welcome message]]

=== FPS Scripting ===

* [[Creating a shop script]]
* [[How to make characters talk with text pop-up windows]]
* [[How to make characters give you quests]]
* [[making picked up items visible in your inventory]]
* [[How to make a trigger load another map]]
* [[Making Echoes]]
* [[How to make triggered elevators/platforms]]
* [[How to make items that can be picked up]]

=== RPG Scripting ===
* [[RPG commands]]
* [[RPG configuration]]
* [[RPG script]]

== Source Code Modifying + Recompiling ==

* [[Compiling the source code]]
* [[How to get a mapsize greater than 16]]
* [[How to add creatures]]
* [[How to add more player character models]]

== Multiplayer tutorials ==

* [[How to host a coop edit session over the internet]]
* [[How to host a persistent world in Sandbox over the internet]]
* [[How to monitor your dedicated server without being in it]]

== Unsorted tutorials ==
* [[Transferring your Map to a new version of Sandbox]]
* [[How to save a map properly]]
* [[How to add projectiles to your game]]
* [[How to automatically save your map every x number of minutes]]

== Sandbox Related ==
=== Within Sandbox ===
* [[Guide to a good game]]
* [[Customizing Sandbox]]
* [[Adding custom songs to Sandbox]]
* [[Preparing your map for uploading]]
* [[Using Cullart]]
* [[How to capture screen shots and videos]]
* [[How to set up Sandbox for commercial use]]

=== Outside of Sandbox ===
* [[Licensing]]
* [http://forum.sandboxgamemaker.com/viewtopic.php?f=24&t=1493 Copyrighting your content]

==Content Creation==
* [[Why Create Content?]]
* [[Tips on creating content]]
* [[Good free programs for Sandbox]]
* [[Content Creation Software Tutorials List]]
===3D Art===
* [[Models Vs. Geometry]]
===2D Art===
* [[Making Seamless textures]]
* [[How to make new textures]]
* [[Creating special shader maps for textures]]
* [[Glowmaps]]
* [http://www.leighvanderbyl.com/texturing-for-dummies/ Texturing for Dummies]
* [http://www.cgsociety.org/index.php/CGSFeatures/CGSFeatureSpecial/the_top_ten_tips_of_texturing Top Ten Tips of Texturing]
* [http://forums.cgsociety.org/showthread.php?t=373024 Hard Surface Texture Painting]

== Meta-Sandbox ==
* [[How to contribute to Platinum Arts Sandbox]]
* [[Where to find inspiration]]
* [[Editing the wiki]]

* [[Creators of these tutorials]]

RPG commands

2012-10-23T14:23:54Z

Kddekadenz:

Here is a list of most RPG commands (wrote a small program to output them):

''rpg.cpp''
<code>
 
primaryattack 
secondaryattack 
hotkey 
include "path/to/script" 
r_rehash 
newgame "gamename" 
map "mapname" 
newmap
</code>

''rpgai.cpp''
<code>
 
r_action_clear 
r_action_attack 
r_action_move 
r_action_wander
</code>

''rpgcamera.cpp''
<code>
 
cs_interp_ ## name 
cs_start 
cs_interrupt 
cs_post 
cs_action_generic 
cs_action_movedelta 
cs_action_moveset 
cs_action_movecamera 
cs_action_moveent 
cs_action_viewdelta 
cs_action_viewset 
cs_action_viewcamera 
cs_action_viewent 
cs_action_focus 
cs_action_follow 
cs_action_viewport 
cs_container_generic 
cs_container_translate 
cs_container_scale 
cs_container_rotate 
cs_element_text 
cs_element_image 
cs_element_solid
</code>

''rpgconfig.cpp''
<code>
 
r_select_ ## c 
r_num_ ## c 
r_select_ ## c 
r_select_item_use 
r_num_item_use 
r_script_say 
r_script_signal "signalname" [code] 
r_mapscript_signal 
r_status_addgeneric 
r_status_addpolymorph 
r_status_addlight 
r_status_addsignal 
r_status_addscript 
r_status_get_effect 
r_status_num_effect 
r_item_use_new_consumable - does not work yet 
r_item_use_new_armour 
r_item_use_new_weapon 
r_recipe_add_ingredient "item index" 
r_recipe_add_catalyst "item index" 
r_recipe_add_product "item index" 
r_recipe_get_ingredient 
r_recipe_get_catalyst 
r_recipe_get_product 
r_recipe_num_ingredient 
r_recipe_num_catalyst 
r_recipe_num_product 
r_ammo_add_item 
r_ammo_num_item 
r_ammo_get_item 
r_faction_set_relation 
r_faction_get_relation 
r_global_new "value" 
r_tip_new "text of tip" 
r_cat_new "categoryname"
</code>

''rpggui.cpp''
<code>
 
r_buystack_get 
r_buystack_value 
r_buystack_add 
r_buystack_remove 
r_sellstack_get 
r_sellstack_value 
r_sellstack_add 
r_sellstack_remove 
r_dotrade 
r_get_dialogue 
r_num_response 
r_get_response 
r_trigger_response 
</code>

''rpghud.cpp''
<code>
 
r_hud_minimap 
r_hud_horizbar 
r_hud_vertbar 
r_hud_text 
r_hud_image 
r_hud_solid
r_hud
</code>

''rpgscript.cpp''
<code>
 
r_stack 
r_sleep <time> 
worlduse 
r_cansee <actor reference> 
r_preparemap "mapname" 
r_reftype 
r_registerref 
r_registertemp 
r_setref 
r_swapref 
r_matchref 
r_ref_len 
r_ref_push 
r_ref_remove 
r_global_get $globalname 
r_global_set $globalname value 
r_cat_get <item index> 
r_loop_maps 
r_loop_ents 
r_loop_aeffects 
r_loop_inv 
r_setref_invstack 
r_setref_inv 
r_loop_equip 
r_setref_equip 
r_loop_veffects 
r_get_attr <actor reference> 
r_get_skill <actor reference> 
r_get_weight <actor reference> 
r_get_name <actor reference> 
r_get_type <actor reference> 
r_get_base <actor reference> 
r_get_use <actor reference> 
r_get_state <actor reference> 
r_get_pos <actor reference> 
r_get_faction <actor reference> 
r_add_effect 
r_kill <actor reference> 
r_resurrect <actor reference> 
r_pickup 
r_additem <actor reference> <item index> 
r_get_amount <actor reference> <item index> 
r_drop 
r_remove <actor reference> <item index> 
r_canequip 
r_equip 
r_dequip 
r_transfer 
r_trigger 
r_destroy 
r_get_mana 
r_get_maxmana 
r_get_manaregen 
r_get_health 
r_get_maxhealth 
r_get_healthregen 
r_get_resist 
r_get_thresh 
r_get_neededexp 
r_get_maxweight 
r_get_maxspeed 
r_get_jumpvel 
r_invest_attr 
r_invest_skill 
r_givexp <actor reference> <item index> 
r_get_lastaction 
r_get_charge 
r_get_primary 
r_get_secondary 
r_check_recipe 
r_use_recipe 
r_learn_recipe 
r_chat 
r_response "message" "node" 
r_trade 
r_loot 
r_num_ents 
r_on_map 
r_spawn_ ## type 
r_teleport 
r_get_status_group 
r_get_status_owner 
r_get_status_num 
r_get_status 
r_get_status_duration 
r_get_status_remain 
r_sound "path/to/sound" 
r_journal_record 
r_journal_loop_buckets 
r_journal_loop_entries
</code>

RPG commands

2012-10-07T16:08:37Z

Kddekadenz: Created page with 'Here is a list of most RPG commands (wrote a small program to output them): ''rpg.cpp'' <code> primaryattack secondaryattack hotkey include r_rehash <br…'

Here is a list of most RPG commands (wrote a small program to output them):

''rpg.cpp''
<code>
 
primaryattack 
secondaryattack 
hotkey 
include 
r_rehash 
newgame 
map 
newmap
</code>

''rpgai.cpp''
<code>
 
r_action_clear 
r_action_attack 
r_action_move 
r_action_wander
</code>

''rpgcamera.cpp''
<code>
 
cs_interp_ ## name 
cs_start 
cs_interrupt 
cs_post 
cs_action_generic 
cs_action_movedelta 
cs_action_moveset 
cs_action_movecamera 
cs_action_moveent 
cs_action_viewdelta 
cs_action_viewset 
cs_action_viewcamera 
cs_action_viewent 
cs_action_focus 
cs_action_follow 
cs_action_viewport 
cs_container_generic 
cs_container_translate 
cs_container_scale 
cs_container_rotate 
cs_element_text 
cs_element_image 
cs_element_solid
</code>

''rpgconfig.cpp''
<code>
 
r_select_ ## c 
r_num_ ## c 
r_select_ ## c 
r_select_item_use 
r_num_item_use 
r_script_say 
r_script_signal 
r_mapscript_signal 
r_status_addgeneric 
r_status_addpolymorph 
r_status_addlight 
r_status_addsignal 
r_status_addscript 
r_status_get_effect 
r_status_num_effect 
r_item_use_new_consumable 
r_item_use_new_armour 
r_item_use_new_weapon 
r_recipe_add_ingredient 
r_recipe_add_catalyst 
r_recipe_add_product 
r_recipe_get_ingredient 
r_recipe_get_catalyst 
r_recipe_get_product 
r_recipe_num_ingredient 
r_recipe_num_catalyst 
r_recipe_num_product 
r_ammo_add_item 
r_ammo_num_item 
r_ammo_get_item 
r_faction_set_relation 
r_faction_get_relation 
r_global_new 
r_tip_new 
r_cat_new
</code>

''rpggui.cpp''
<code>
 
r_buystack_get 
r_buystack_value 
r_buystack_add 
r_buystack_remove 
r_sellstack_get 
r_sellstack_value 
r_sellstack_add 
r_sellstack_remove 
r_dotrade 
r_get_dialogue 
r_num_response 
r_get_response 
r_trigger_response 
</code>

''rpghud.cpp''
<code>
 
r_hud_minimap 
r_hud_horizbar 
r_hud_vertbar 
r_hud_text 
r_hud_image 
r_hud_solid
r_hud
</code>

''rpgscript.cpp''
<code>
 
r_stack 
r_sleep 
worlduse 
r_cansee 
r_preparemap 
r_reftype 
r_registerref 
r_registertemp 
r_setref 
r_swapref 
r_matchref 
r_ref_len 
r_ref_push 
r_ref_remove 
r_global_get 
r_global_set 
r_cat_get 
r_loop_maps 
r_loop_ents 
r_loop_aeffects 
r_loop_inv 
r_setref_invstack 
r_setref_inv 
r_loop_equip 
r_setref_equip 
r_loop_veffects 
r_get_attr 
r_get_skill 
r_get_weight 
r_get_name 
r_get_type 
r_get_base 
r_get_use 
r_get_state 
r_get_pos 
r_get_faction 
r_add_effect 
r_kill 
r_resurrect 
r_pickup 
r_additem 
r_get_amount 
r_drop 
r_remove 
r_canequip 
r_equip 
r_dequip 
r_transfer 
r_trigger 
r_destroy 
r_get_mana 
r_get_maxmana 
r_get_manaregen 
r_get_health 
r_get_maxhealth 
r_get_healthregen 
r_get_resist 
r_get_thresh 
r_get_neededexp 
r_get_maxweight 
r_get_maxspeed 
r_get_jumpvel 
r_invest_attr 
r_invest_skill 
r_givexp 
r_get_lastaction 
r_get_charge 
r_get_primary 
r_get_secondary 
r_check_recipe 
r_use_recipe 
r_learn_recipe 
r_chat 
r_response 
r_trade 
r_loot 
r_num_ents 
r_on_map 
r_spawn_ ## type 
r_teleport 
r_get_status_group 
r_get_status_owner 
r_get_status_num 
r_get_status 
r_get_status_duration 
r_get_status_remain 
r_sound 
r_journal_record 
r_journal_loop_buckets 
r_journal_loop_entries
</code>

RPG

2012-10-07T15:58:10Z

Kddekadenz: /* References */

The RPG is currently still in heavy development with many features still unimplemented. With the advent of the 2.7.0 release it has entered the Alpha stage. It may still change dramatically in the near future, but the various interfaces at this point are more or less stable and should function correctly with future releases.

=References=
* [[RPG configuration|Configuration and Definitions]]
* [[RPG script|Scripting]]
* [[RPG_commands|Commands]]
* [[RPG_cutscene|Cutscenes]]
* [[RPG gui|GUIs]]
* [[RPG hud|HUDs]]

=Tutorials=
* [[RPG editing|Editing tips]]
* [[RPG tutorial|Tutorial]]

=Misc. pages=
* [[RPG todo|todo]]

=Internals=

The creator is capable of defining and manipulating a great many facets of his game, and future releases promise to increase these capabilities and freedoms.

== Cutscenes ==

Cutscenes unlike definitions can contain things other than numbers in their names and aren't loaded into memory until they are needed. Cutscenes '''can always be skipped''' and you as the creator should therefor make sure that the post script takes care of any changes of state that need to happen, additionally during cutscenes are the only time the player can be commanded via AI commands.

There are two parts to the cutscene system, the first is directives for the camera and the second are 2D elements to be drawn on screen and their containers.

with respect to the 2D elements, the cutscene system functions like the HUD in this regard, fitting a proportionally scaled 1600x1200 virtual screen into yours and then adjusting the size to cover the entire screen and storing the size in the hud_right and hud_bottom variables.

Containers basically group a series of actions together and influences them in some way (eg, rotates 2D elements). Containers are destroyed when they no longer possess any children. A very handy use for these are to allow layers. For example, you could create a slide container and a subtitle container, this will result in the subtitles always being drawn above the slides.

== Definitions ==

The creator can define just about anything, from creatures, monsters, maps, containers, scripts, dialogue, cutscenes, HUDs, GUIs and particle effects. The definitions are sourced from the game's data directory and can be changed in real time during the game. It should be noted that unless things use these definitions as a template, any effects from ingame modifications will not persist across sessions. We therefor recommend that you only use those that accept references as any changes to them will persist unless you simply wish to test and fine tine some variables quickly and easily.

Also note that all definitions must be defined in a separate text file named solely by a number with a .cfg extension. Any other .cfg files will throw warnings and the game will abort if there are any gaps. At least that is true for the hard-coded directories - you may add additional ones and use '''include''' to include their files in your scripts and definitions.

For example, there is a definition for a bear creature with 40 strength. I might increase this to 90 in game, but any existing bears will still have 40 strength. Likewise I could create a few new bears which would then have 90 strength. if I was to save and reload my game, any new bears will have 40 strength but those spawned with 90 strength will still exist and walk about.

== Game state ==

All map related information, short of the map's entities, waypoints and geometry are stored in a hashtable. This hashtable includes the properties of the map, the script, the name and the entities currently present as well as any queued actions that are awaiting the player's arrival.

Generally speaking, any map besides the current map isn't updated and is in a state of limbo until the player goes there.

== GUIs ==

The RPG defines a series of commands to facilitate the creation of custom GUIs, unlike previous iterations the GUI isn't hard coded although it depends on a few hard coded names.

Essentially all the RPG does in relation to this is to force the talk GUI open during conversations and to pause the game while a GUI is open. newui currently isn't properly supported.

== HUDs ==

The placement of all HUD entities are defined entirely through script, the script itself is evaluated once every update and can be redefined at any part of the game using a r_hud invocation.

The HUD pretends to be a 1600x1200 screen scaled to fit inside your screen and then has its dimensions adjusted, these dimensions are stored in the variables, hud_right and hud_bottom which you should query when you draw items offset from the bottom or the right. The only benefit of using such a size is that it's far easier to get a sense of scale and to understand in general than a 0.f to 1.f range.

In case you're wondering why there is a hud_bottom and not a hud_up, the reason is that the screen coordinates are flipped and that the top left is therefor (0, 0), not the bottom left.

== Multiplayer ==

The RPG wasn't designed to accommodate multiplayer. We may consider NWN style coop sometime in the distant future but the RPG simply lacks any multiplayer capability what so ever.

In other words, this module is presently single player only and will likely remain so.

== Savegames ==

Savegames store the game state and the game definition source. Definitions and the AI's state isn't stored, the one exception is recipes in which a portion of the flags slot is saved. specifically the portion that tells us if the player knows the recipe.

Otherwise, everything is saved in a compressed archive, from maps and their contents, to the various properties of each and every existing entity to the whole reference table.

It should be noted that you cannot save at certain points, specifically during dialogue, cutscenes, in editmode and on maps with the F_NOSAVE flag set.

== Scripts ==

Scripts are signal based, you define a signal to listen for and a set of actions to execute when that signal is received. There are several types, those the game sends on every update, those the game sends under certain conditions and those the creator manually sends himself via r_signal.

The second and probably the most important facet of scripting is the use of references. The reference system is type safe, prone to whining (the solution is to fix what it's complaining about, not ignore it) and is implemented as a layer utilising cubescript as opposed to being a part of it.

The reference system is implemented as an array of hashtables, which introduces the concept of scope and shadowing and there are also some hard-coded reserved references. At present these are specifically, "player", "curmap", "talker", "self" and "actor", you should not change them and they will likely be read only in the near future. In addition there are also temporary references, these aren't saved in the save game and are cleared at the end of the update cycle. Some of the destinations may persist for a long time but there is no such guarantee.

RPG tutorial

2012-09-02T17:17:22Z

Kddekadenz: /* Part 7 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3 - items=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
r_item_value 2
r_item_weight 1
r_item_category $cat_misc
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
r_item_value 23
r_item_weight 2
r_item_category $cat_weap
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
r_item_value 10
r_item_weight 5
r_item_category $cat_weap
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
r_item_value 4
r_item_weight 1
r_item_category $cat_misc
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4 - magic=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5 - monsters=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6 - a simple quest=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7 - a basic puzzle=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:16:14Z

Kddekadenz: /* Part 6 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3 - items=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
r_item_value 2
r_item_weight 1
r_item_category $cat_misc
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
r_item_value 23
r_item_weight 2
r_item_category $cat_weap
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
r_item_value 10
r_item_weight 5
r_item_category $cat_weap
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
r_item_value 4
r_item_weight 1
r_item_category $cat_misc
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4 - magic=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5 - monsters=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6 - a simple quest=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:15:34Z

Kddekadenz: /* Part 5 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3 - items=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
r_item_value 2
r_item_weight 1
r_item_category $cat_misc
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
r_item_value 23
r_item_weight 2
r_item_category $cat_weap
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
r_item_value 10
r_item_weight 5
r_item_category $cat_weap
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
r_item_value 4
r_item_weight 1
r_item_category $cat_misc
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4 - magic=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5 - monsters=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:14:39Z

Kddekadenz: /* Part 4 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3 - items=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
r_item_value 2
r_item_weight 1
r_item_category $cat_misc
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
r_item_value 23
r_item_weight 2
r_item_category $cat_weap
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
r_item_value 10
r_item_weight 5
r_item_category $cat_weap
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
r_item_value 4
r_item_weight 1
r_item_category $cat_misc
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4 - magic=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:13:05Z

Kddekadenz: /* Part 3 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3 - items=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
r_item_value 2
r_item_weight 1
r_item_category $cat_misc
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
r_item_value 23
r_item_weight 2
r_item_category $cat_weap
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
r_item_value 10
r_item_weight 5
r_item_category $cat_weap
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
r_item_value 4
r_item_weight 1
r_item_category $cat_misc
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:07:13Z

Kddekadenz: /* Part 2 - the first NPC */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self main
]
r_chat self quest
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_node "normal" [result "Things the creatures say are simply typed like this, no surrounding quotes"] []
r_script_node "emphasis" [result "If you wish to put *emphasis* on a word, place *'s on both sides]"] []
r_script_node "actions" [result "[between these brackets, write what your character sees and experiences]"] [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:04:03Z

Kddekadenz: /* Part 2 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2 - the first NPC=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self 0
]
r_chat self 2
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_say "Things the creatures say are simply typed like this, no surrounding quotes" []
r_script_say "If you wish to put *emphasis* on a word, place *'s on both sides]" []
r_script_say "[between these brackets, write what your character sees and experiences]" [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:03:24Z

Kddekadenz: /* Part 1 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1 - initial skeleton=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self 0
]
r_chat self 2
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_say "Things the creatures say are simply typed like this, no surrounding quotes" []
r_script_say "If you wish to put *emphasis* on a word, place *'s on both sides]" []
r_script_say "[between these brackets, write what your character sees and experiences]" [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T17:02:17Z

Kddekadenz: /* Part 2 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "glad" //goes to the node glad
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "glad" [result "I'm glad to hear it"] [
r_response "Goodbye" ""
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self 0
]
r_chat self 2
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_say "Things the creatures say are simply typed like this, no surrounding quotes" []
r_script_say "If you wish to put *emphasis* on a word, place *'s on both sides]" []
r_script_say "[between these brackets, write what your character sees and experiences]" [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

RPG tutorial

2012-09-02T16:58:45Z

Kddekadenz: /* Part 6 */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_say "Hello, how are you doing" [ // 0 - it's good practice to number your entries
r_response "I'm well, yourself?" 1 //goes to dialogue #1
r_response "Goodbye" -1 //closes the dialogue
]

r_script_say "I'm glad to hear it" [ // 1
r_response "Goodbye" -1
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self 0
]
r_chat self 2
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_say "Things the creatures say are simply typed like this, no surrounding quotes" []
r_script_say "If you wish to put *emphasis* on a word, place *'s on both sides]" []
r_script_say "[between these brackets, write what your character sees and experiences]" [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
// its type is also "magic" which means its efficiency is reduced by magic resisting items.
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg - ''the following code parts are all out of the same cfg, they are just separated for better readability''
<code>
r_script_node "main" [result "Hello, how are you doing"] [
r_response "I'm well, yourself?" "howareyou" //goes to the node howareyou
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" "work"
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" "noreward"
] [
r_response "I brought you the mcGuffin" "missing"
]
] 2 [
r_response "Do you have any more work for me?" "nowork"
]
r_response "Goodbye" "" //closes the dialogue
]

r_script_node "howareyou" [result "I'm glad to hear it" [
r_response "Goodbye" ""
]

r_script_node "work" [result "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [
r_response "You can count on me!" "wait" [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" ""
]

r_script_node "wait" [result "Great! I'll be waiting for your return" [
r_response "[End]" ""
]

r_script_node "noreward" [result "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [
r_response "[Give him the mcGuffin]" "thankyou" [
r_remove player 7 1 //remove the mcGuffin out of players inventory
r_givexp player 900 //give player some exp in return
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" ""
]

r_script_node "thankyou" [result "Thank you very much, I will never forget this" [
r_response "[End]" ""
]

r_script_node "missing" [result "Where is it?" [
r_response "I must've forgotten it in the cave..." ""
]

r_script_node "nowork" [result "No, but once again, thank you for getting this for me" [
r_response "Farewell" ""
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''
The journal is to record rumours, quest notes, deeds, obituaries and all kinds of other things.

<code>
r_journal_record "mcGuffin" "I shall go into the cave to the North-West of this valley and retrieve the mcGuffin."
</code>
This will add to the entry mcGuffin in your journal the message "I shall go into..".

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

<Broken Link Removed>

Tutorials List

2012-05-14T17:03:37Z

Kddekadenz: /* Modules */

== Getting, Installing and opening Sandbox ==

* [[Downloading Sandbox]]
* [[Installing Sandbox]]
* [[Running Sandbox]]
* [[development|Obtaining the development version]]

== Modules ==

* [[FPS|FPS - First Person Shooter (default)]]
* [[SSP|SSP - Side Scrolling Platformer]]
* [[RPG|RPG - Role Playing Game]]
* [[RPG tutorial|RPG Tutorial]]
* [[MovieCube|MovieCube - Machinima Tool]]
* [[Vehicle Simulator]]

== Learning the editor basics ==

* [[Map Editing Basics]]
* [[How to change textures in your map]]
* [[How to place 3D grass]]
* [[How to add lava, water, glass and other materials to your map]]
* [[How to make ramps, bridges, and angles]]
* [[How to make invisible boundaries]]
* [[Tips on making a good map]]
* [[Gridwork]]

=== Buildings ===

* [[How to make sloped roofs]]
* [[How to make secret doors, walls & floors]]
* [[How to make 1-way windows only you can see out of]]
* [[How to make 1-way doors]]
* [[How to create a hollow tower/tube]]
* [[How to make stairs you could walk up]]
* [[How to create set of glass stairs]]
* [[How to make a TV]]
* [[How to make various window shapes]]
* [[How to create a spiral staircase]]
* [[How to make a pyramid/four-sided sloped roof]]

=== Terrain editing ===

* [[How to create mountains, ponds, and oceans]]
* [[How to transfer parts of a map to a new one]]
* [[How to make a forest]]
* [[How to make a cave]]
* [[How to make a realistic river]]
* [[How to make a swimming pool]]
* [[How to make a fountain]]
* [[How to create smooth curvy pathways]]
* [[How to create fields with flower patches]]
* [[How to create a camp fire and fireplace]]
* [[How to make a bumpy road]]
* [[How to make various types of fences]]
* [[How to make a nice waterfall]]
* [[How to edit terrain properly]]
* [[How to fix bad terrain or geometry errors]]
* [[How to make railings]]
* [[Texture Blending]]

=== Advanced Editor Techniques===

* [[How to create a slide]]
* [[How to create a trampoline]]
* [[How to create electric fences]]
* [[How to make a sphere shapes in 'edit mode']]
* [[How to make curved shapes in 'edit mode']]
* [[How to create curved glass]]
* [[How to create climbable ladders and vertical walls]]
* [[How to make an endless slide]]
* [[How to create lens flares]]
* [[How to make a snowman]]
* [[How to make a boat]]
* [[How to create warp speed tunnels]]
* [[How to create hidden teleports]]
* [[How to create spinning palm trees]]
* [[How to change gravity]]

== Lighting and Particle effects ==

* [[How to add various lighting]]
* [[Lighting|How to light a map properly]]
* [[Tips to make a night time map]]
* [[Tips to make a morning map]]
* [[Tips to make a sunset map]]
* [[How to add particle effects]]
* [[How to create snow or rain]]
* [[How to put fog to a map]]
* [[Useful lighting commands]]

== Models and Sandbox ==

* [[Blender to Sandbox]]
* [[Wings3D to Sandbox flash tutorials]]
* [[Importing .OBJ files]]
* [[Mapmodels|Loading and adding mapmodels]]
* [[How to add new models]]
* [[Creating 3D models with PAS]]
* [[How to add new colors of creatures and map models]]

== Textures ==

* [[Glowmaps]]
* [[Adding custom textures to a new map]]
* [[Adding custom textures with normal maps]]
* [[Making Seamless textures]]
* [[How to make new textures]]
* [[Creating special shader maps for textures]]
* [http://www.leighvanderbyl.com/texturing-for-dummies/ Texturing for Dummies]
* [http://www.cgsociety.org/index.php/CGSFeatures/CGSFeatureSpecial/the_top_ten_tips_of_texturing Top Ten Tips of Texturing]
* [http://forums.cgsociety.org/showthread.php?t=373024 Hard Surface Texture Painting]

== Scripting/Trigger tutorials ==

* [[Menu Editing|How to modify the menu]]
* [[making picked up items visible in your inventory]]
* [[How to make a trigger load another map]]
* [[Cubescript]]
* [[Creating easy spells]]
* [[Removing Editmode]]
* [[Making Echoes]]
* [[Adding Custom Skyboxes]]
* [[How to make triggered elevators/platforms]]
* [[How to make items that can be picked up]]
* [[How to make moving doors and platforms in single player mode]]

=== NPCs ===

* [[Creating a shop script]]
* [[How to make characters talk with text pop-up windows]]
* [[How to make characters talk with a voice recording]]
* [[How to make characters give you quests]]
* [[How to add bots and train them]]
* [[Ultimate Simple Script Guide, Part 1]]
* [[Ultimate Simple Script Guide, Part 2]]

== Source Code Modifying + Recompiling ==

* [[Compiling the source code]]
* [[How to get a mapsize greater than 16]]
* [[How to add creatures]]
* [[How to add more player character models]]

== Multiplayer tutorials ==

* [[How to host a coop edit session over the internet]]
* [[How to host a persistent world in Sandbox over the internet]]
* [[How to monitor your dedicated server without being in it]]

== Unsorted tutorials ==
* [[Transfering your map from one sandbox version to another]]
* [[How to save a map properly]]
* [[How to add projectiles to your game]]
* [[How to automatically save your map every x number of minutes]]

== Sandbox Related ==
=== Within Sandbox ===
* [[Guide to a good game]]
* [[Customizing Sandbox]]
* [[Adding custom songs to Sandbox]]
* [[Preparing your map for uploading]]
* [[Using Cullart]]
* [[How to capture screen shots and videos]]

=== Outside of Sandbox ===
* [[Licensing]]
* [http://forum.sandboxgamemaker.com/viewtopic.php?f=24&t=1493 Copyrighting your content]
* [[Tips on creating content]]
* [[Models Vs. Geometry]]

=== Maptitle and authors ===
* [[How to add map title and author]]
* [[How to change color of text in maps welcome message]]

== Meta-Sandbox ==
* [[How to contribute to Platinum Arts Sandbox]]
* [[Where to find inspiration]]
* [[Editing the wiki]]

* [[Creators of these tutorials]]

RPG tutorial

2012-04-17T10:46:58Z

Kddekadenz: /* Extras */

The following tutorials are only meant to cover the basics of developing for the RPG. Each of the tutorials build upon the work from the previous exercises and are therefor best done in order.

=Part 1=

This part covers making the initial skeleton of our game.

By default the RPG detects the available games by searching data/rpg/games for cfg files, these files form the basis of what the main menu will list as the available games. In selecting a game from the menu, it will then attempt to load the definitions from an equivalently named directory.

We now know the first step to making our own tutorial game, we need a corresponding cfg and directory inside ''data/rpg/games'''

Luckily sandbox comes with a base that can be derived to quickly get things up and running, so first up, let's make a copy of the base directory and call the copy "tutorial" and then move a file named '''base.cfg''' inside '''data/rpg/games/tutorial''' into '''data/rpg/games''' and rename it to '''tutorial.cfg'''.

We can essentially open up our game in sandbox now, but we still have a few things to do, so for now, open up '''tutorial.cfg''' in your favourite text editor. The contents should be pretty self explanatory but we do need to make a few specific changes.

Firstly, we want to set the default map and associate it with mapscript 0, for this excercise we'll name our map tutorial1.

Secondly, we want to set the version number and the compatibility number to 1.

Finally, we will want to specify a HUD to use for our game. Sandbox currently only ships one, so we will execute it here.

The final version of tutorial.cfg should look similar to this

<code>
r_preparemap tutorial1 0

firstmap tutorial1

gameversion 1
compatversion 1

exec data/rpg/hud_standard.cfg
</code>

Save it and we have one more step to go, we need to make a map named tutorial1, so fire up sandbox and save a newmap under that name.

Congratulations! you have successfully set up the basics required to make your RPG with sandbox

==Addendum==

game.cfg has two explicit purposes. Firstly it identifies the existence of a game and secondly, it defines many of the important attributes of the game.

things that can and should be defined in game.cfg include
* the script and flags to use on a maps
* internal properties, such as the game version
* global game properties, such as friendly fire
* rule properties (currently not available)
* the initial/default HUD

'''I'm a windows'''

If windows is your operating system of choice, do yourself a huge favour and at the very least configure windows to display file extensions such as .cfg. This will save you a fair bit of pain

=Part 2=

This section of the tutorial involves spawning a neutral NPC and assigning him some dialogue

We can go about this in a few ways, but we'll start by first defining the NPC's script, the NPC, and then creating a place for him in the world.

First off, go to your definitions directory (probably data/rpg/games/tutorial) and then enter the script subdirectory. You will not want to create a new configuration file and place it at the very end of the others (eg, if the last is named 7.cfg, name yours 8.cfg). In this file, we define how any entities using it will react and interact with the surrounding world. Since we don't want to bother with that, we will simply include the default NPC script.

Afterwards we can start defining the dialogue. When you're done the final script should look something like this. Feel free to experiment by writing more dialogue and fleshing out your character

<code>
include scripts/1 //includes the default NPC script

r_script_say "Hello, how are you doing" [ // 0 - it's good practice to number your entries
r_response "I'm well, yourself?" 1 //goes to dialogue #1
r_response "Goodbye" -1 //closes the dialogue
]

r_script_say "I'm glad to hear it" [ // 1
r_response "Goodbye" -1
]
</code>

With that taken care of, we will now define a critter to use the script. All critter configuration options are prefixed with r_char and most contain a variant with a _get suffix for retrieving the value. Now create a new cfg file in the critter sub directory, following the same steps as you did for the script to define it's name. This will probably be 0.cfg.

Consult the configuration reference for a full list of available configuration options, for now, copy the following into critters/0.cfg

<code>
r_char_name "Bob"
r_char_mdl "ogre"
r_char_script 8 //make sure this corresponds with the above script
</code>

Finally, we need to spawn Bob, so start your game and create a critter entity that spawn a critter of type 0. Remember that F1 toggles editmode in the RPG!
<code>
newent critter 0
</code>

You're done, to test it simply exit editmode and press E while hovering the crosshair over him.

==Addendum==

'''Default Scripts'''

The various definition types of the RPG each default to their own individual specialized script. They correspond as follows
* 0 - null/empty/nothing
* 1 - Default critter script; primarily initiates dialogue, will in the future control AI logic and stealth abilities
* 2 - Default item script; mainly implements pickup
* 3 - Default obstacle script; does nothing
* 4 - Default container script; will eventually allow you to pick the lock and loot items
* 5 - Default platform script; does nothing
* 6 - Default trigger script; toggles triggered state (eg, switches door between open and close)

Note that the player defaults to script 0, and has its script explicitly set to 7. Script 7 contains some basic player logic, mainly it lets you know when you level up.

'''Definition numbering'''

The numbers allows the game to easily and quickly identify and order definitions, unfortunately this is inconvenient to the users since it makes identifying which definition corresponds to an item you're looking for a bit of a chore. The only thing you need to remember, is that each definition must be assigned number from 0 and up and that there cannot be '''any''' empty gaps. Duplicate numbers (eg hex or octal) and non-number names will throw a warning.

<code>
$ ls
1.cfg 2.cfg 3.cfg 4.cfg 5.cfg
# the game will abort with these files
</code>

<code>
$ ls
0.cfg 1.cfg 2.cfg 3.cfg 4.cfg
# the game will start
</code>

'''Multiple dialogue entry points'''

The entry point is defined by the talk signal, by default this simply opens the dialogue at position 0 should it exist. If you'd like to change the entry point you will have to redefine the talk signal for your entity. For example...
<code>
r_script_signal talk [
if $cond [
r_chat self 0
]
r_chat self 2
]
]
</code>

You can add more more conditions and variables and you are allowed the full range of cubescript commands.

'''Dialogue standards'''

There are no fixed standards, but we recommend the following conventions when writing dialogue for your characters.

<code>
r_script_say "Things the creatures say are simply typed like this, no surrounding quotes" []
r_script_say "If you wish to put *emphasis* on a word, place *'s on both sides]" []
r_script_say "[between these brackets, write what your character sees and experiences]" [
r_response "[Likewise, place any actions your character takes here]"
]
</code>

=Part 3=

This section of the tutorial covers basic item definitions, trigger basics and crafting.

For this exercise we will craft papyrus sheets, we will write on these to produce our weapon in the next part. This process demands the use of a knife, a hammer and something heavy to compress it while drying. The important part is the materials that are used in the process and those that enable the process, we recommend ignoring the process itself.

So first up, let's define the ingredients, the tools we're going to use and the product we're going to make. If you've followed the tutorial thus far, you should still have 0 item definitions, otherwise follow the previously defined rules. Save the following in the items subdirectory. The commands and their effect should be self-explanatory

0.cfg
<code>
r_item_name "Papyrus reed"
r_item_description "Freshly harvested from the Papyrus plant, the stem of these reeds have been used for centuries to create a durable writing surface."
r_item_mdl "tentus/moneybag"
</code>

1.cfg
<code>
r_item_name "Old Knife"
r_item_description "The blade has seen a lot of use and is missing a few chips, but remains deadly sharp."
r_item_mdl "tentus/moneybag"
</code>

2.cfg
<code>
r_item_name "Old Mallet"
r_item_description "The mallet appears to have seen a lot of use, but remains effective for beating things."
r_item_mdl "tentus/moneybag"
</code>

3.cfg
<code>
r_item_name "Papyrus"
r_item_description "Papyrus reeds have been converted into a durable surface suitable for writing on."
r_item_mdl "tentus/moneybag"
</code>

Next, we will define the recipe. A recipe has 3 lists of items, the ingredients, the catalysts and the products. Ingredients are items that are consumed in full to produce the products and catalysts are items that enable the process to happen.

For now, copy the following to '''recipes/0.cfg'''
<code>
r_recipe_flags $RECIPE_KNOWN //we know the recipe at the start

r_recipe_add_ingredient 0 10 // 10 x papyrus reeds

r_recipe_add_catalyst 1 1 // 1 x knife
r_recipe_add_catalyst 2 1 // 1 x hammer

r_recipe_add_product 3 1 // 1 x papyrus
</code>

We now have everything we need to create the final item, we simply need to spawn them into the world. If you are in a hurry to test it out, use the following commands to spawn them in the world.

<code>
newent item 0 10 //skip this if you aren't in a hurry
newent item 1 1 //knife
newent item 2 1 //hammer
</code>

If you're still here, we're now going to make actual harvestable papyrus plants using triggers, since we lack a suitable model we will improvise using one for reeds. First we will define a suitable script. Our trigger's script will add a random amount between 1-4 reeds to the player's inventory and then destroy itself. If we wanted, we could toggle a variable and change the model so it looks as though it was harvested and perhaps even respawn it after a few while of game time, but that's a more advanced topic for another time. So for now, copy the following into '''scripts/9.cfg'''.

<code>
//papyrus reeds

r_script_signal interact [
// adds between 1-4 units of papyrus to whoever harvests it
r_additem actor 0 (rnd 5 1)
// removes itself from the stack
r_destroy self
]
</code>

As for the trigger itself, copy the following into '''triggers/0.cfg'''.

<code>
r_trigger_name "Papyrus plant"
r_trigger_mdl "dcp/reed"
r_trigger_script 9
</code>

Congratulations, just spawn a few of those near a body of water somewhere, and you've finish this section of the tutorial. The command is of course as follows

<code>
newent trigger 0
</code>

==Addendum==

'''Splitting the process'''

The general recommendation is to try and contain the whole process in a single recipe. Rather than splitting it out into many small pieces. As a rule, try to avoid making the player learn and execute the process and let taht be handled via the character's knowledge. For example, if we wanted to create stew in a more contemporary setting, the recommended recipe would be something like this.

Ingredients
* 3 x Potatoes
* 1 x Unions
* 5 x Carrots
* 1 x Butane canister

Catalysts
* 1 x Knife
* 1 x Cutting board
* 1 x Pot
* 1 x Portable gas cooker

Products
* 5 x Stew

Likewise, the strongly not recommended series of recipes may look something like this

Ingredients
* 1 x Potato

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced potato

Ingredients
* 1 x Union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced union

Ingredients
* 1 x Sliced union

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Diced union

Ingredients
* 1 x Carrot

Catalysts
* 1 x Knife
* 1 x Cutting board

Products
* 5 x Sliced carrot

Ingredients
* 15 x Sliced Potatoes
* 25 x Diced Unions
* 25 x Sliced Carrots
* 1 x Pot

Products
* 1 x Uncooked Stew

Ingredients
* 1 x Uncooked Stew
* 1 x Butane canister

Catalysts
* 1 x Portable gas cooker

Products
* 1 x Pot
* 5 x Stew

'''Skilled Craftsmen'''

If you want to add a recipe that depends on skills to be used, you can use the r_recipe_reqs family of variables to set them. You're allowed to utilise the full family of stats and skills to define skill requirements for a recipe.

=Part 4=

This part covers covers particle effect definitions, status effect definitions and item usage definitions with the example of a weapon. The player will be able to craft it with the materials from the previous part.

Let's dive right into it. We're going to create 2 items and an additional recipe. For the first item, we need some means of writing on the papyrus we created in the previous session. The second item will be the weapon we will produce, for now we will just create a small skeleton for it. We should currently have 4 items defined, if not adjust numbers accordingly.

4.cfg
<code>
r_item_name "Ink Well"
r_item_description "It is a phial of ink. Paired with a quill these are still very popular writing instruments."
r_item_mdl "tentus/moneybag"
</code>

5.cfg
<code>
r_item_name "Magic Arrow"
r_item_description "Upon this scroll of papyrus rest incantations for a magical spell."
r_item_mdl "tentus/moneybag"
</code>

Next we will define the recipe to produce the weapon, we should currently only have a single recipe, adjust accordingly if this isn't the case.

1.cfg
<code>
r_recipe_flags $RECIPE_KNOWN

r_recipe_add_ingredient 3 1 // 1 x papyrus
r_recipe_add_ingredient 4 1 // 1 x ink

r_recipe_add_product 5 1 // magic arrow scroll
</code>

We now have to deal with the most important part to make any weapons, swords, spells or otherwise. We need a status group to do something. Zero of more status effects comprise each group, and this design decision mainly exists to accommodate spells like polymorph and their respective dispelling. The statuses sub directory should already contain a dummy group, once again, adjust the numbers as required for our own.

1.cfg
<code>
//heavy damage
r_status_friendly 0 //this is decidedly hostile
r_status_addgeneric $STATUS_HEALTH -100 0 // instantly remove 100 HP
</code>

We currently have everything we need to define our weapon/spell, but we unfortunately won't be able to see the projectile at present due to having no particle effects defined. Projectiles can have up to 3 effects, that is the projectile itself, its trail and the explosion at the end. -1 can be substituted in any of the effect slots to disable emissions for that part. We will define the following 2 effects in the effects subdirectory.

0.cfg
<code>
// flying arrow
r_effect_mdl "hirato/arrow"
r_effect_flags 0
</code>

1.cfg
<code>
// purple magic sparkles
r_effect_flags 0
r_effect_particle $PART_STEAM
r_effect_colour 0x3F003F
r_effect_size 0.5
</code>

We now have everything we need to define our weapon fully as well as be able to see any of its attacks. To make the weapon usable, we need to define a use case in which it is a weapon. We have 3 possible use cases, use (eg, read, drink), armour and weapon, the last two are implemented and fully functional while the first isn't. Naturally we want the weapon use case.

So to define our weapon fully, open up items/5.cfg and add the following at the end. Generally speaking you don't need to define quite as many properties, most of these are here just to be sure things work as expected.
<code>
r_item_use_new_weapon // 0 - it's good practice to number these entries

//these slots are available in consume and armour use cases as well
r_item_use_name "Magic Arrow"
r_item_use_description "An arrow is conjoured from the caster's finger tip and flung at its target with sheer mental will."
r_item_use_cooldown 1500
//increases the strength of the spell with player skill or charging
r_item_use_chargeflags $CHARGE_MAG
// adds our status effect at 30% efficiency - with the above charge flag that means 30 damge
r_item_use_new_status 1 $ATTACK_MAGIC 0.3

//these slots are available with armour use cases as well
r_item_use_slots $SLOT_LHAND
r_item_use_skill $SKILL_MAGIC

//these slots are exclusive to weapons
r_item_use_pflags $P_TIME
r_item_use_angle 0
r_item_use_lifetime 1000
r_item_use_gravity 0
r_item_use_projeffect 0 //substitute with your arrow's effect
r_item_use_traileffect 1 //substitute with your trail's effect
r_item_use_deatheffect -1 //replace with a suitable EoL effect
r_item_use_ammo -1 //use mana
r_item_use_cost 15 //uses 15 units of mana
r_item_use_kickback 10
r_item_use_recoil 10
r_item_use_target $T_SINGLE
r_item_use_speed 1.5 // in 100's of cubes a second
</code>

Congratulations! Just spawn the ink well somewhere and craft your weapon, and have some fun. In the next part we will make several mobs for you to use it against.

==Addendum==

'''Reserved ammo types'''

Specifying ammo 0 and above for a use case means you're going to use items from the respective ammo group. In addition there are also 3 additional ammo types that occupy numbers -1, -2 and -3. they are as follows.

* -1 - Mana
* -2 - Health
* -3 - Experience

'''$STATUS_HEALTH, $RECIPE_KNOWN, what is all this stuff!?'''

These are hard coded RPG constants that are reproduced inside data/rpg/game.cfg and are usually kept in sync. We strongly recommend that you use these constants/variables as opposed to using the numbers directly, this helps ensure future compatibility and makes it easier to understand the intended effect of the definitions if updates are required.

The file contains '''all''' of the various flags and numbers that are available in the RPG, so being familiar with them will be a great boon to you if you choose to use sandbox.

=Part 5=

This section of the tutorial covers debug settings, waypoints, and basic AI by making a hostile mob for the player to defeat. Before we even consider adding any AI or monsters, we need to canvas our map with waypoints for the AI to follow and get to the player.

[[File:RPG_tutorial_map.jpg|200px|thumb|right|recommended layout for the first tutorial map]]

But before we get to the waypoints, there is a more critical item to consider, we need to shelter the beast first, so that it doesn't attack the player immediately, specifically so that the player has a chance to build his weapon before taking on the beast. I'd suggest erecting a wall behind Bob's house, see the screenshot on the right for a recommended layout.

Our second order of business is to then enable the AI debug channel so that we can see the waypoints we're dropping and then to canvas the area. Considering the terrain will be mostly flat, you may wish to turn on the experimental waypointing method as well, it will speed up the process tremendously. With that said, waypointing is by far the most tedious task to do sufficiently well in the RPG.

<code>
debug 32 //ai debug channel
dropwaypoints 1 //required to drop waypoints
experimentalwaypoint 1 //method that links to all nearby nodes, as opposed to tracing a path
savewaypoints // saves them when you're done DO NOT FORGET TO DO THIS!!!
</code>

Our first order of business is to make a faction for our mob, at present this is only useful for querying relationships between factions as well as allowing you to hurt each other with friendly fire protection enabled. You may wish to put Bob inside his own faction as well. Copy the following as the definition for the second faction.

1.cfg
<code>
r_faction_name "Beasts"
r_faction_base 0
</code>

We will now define a script for our creature, we want him to attack us if he spots us as well as when we bother or attack him. The ai for now is very basic and will not try to dodge or do anything besides rush in and complete its goal (which is, to kill you). The following will be his script for now.

10.cfg
<code>
//our mob's script
include scripts/1

r_script_signal talk [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal hit [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]

r_script_signal update [
if (r_cansee self player) [
r_action_clear self
r_action_attack self player 1
]
]

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
r_action_clear self
r_action_attack self actor
]
]
</code>

We can now define our beast, let's make him a hungry and aggressive wolf
<code>
r_char_name "Wolf"
r_char_mdl "rpg/characters/wolf"
r_char_script 10
r_char_faction 1

r_char_base_maxspeed 40 //speed boost
r_char_base_jumpvel 80
</code>

We've now done all we need to spawn him, but he won't pose any threat to us at present. For that we need to define a weapon for him and equip it. Since he's a wolf, he would probably use his fangs for a short range low damage attack with little cooldown. So let's define his fangs in the items directory with those properties.

6.cfg
<code>
r_item_name "Fangs"
r_item_description "If you see this, submit a bug report."

r_item_use_new_weapon // 0
r_item_use_cooldown 100
r_item_use_chargeflags $CHARGE_MAG
r_item_use_new_status 1 $ATTACK_SLASH .075

r_item_use_slots (| $SLOT_LHAND $SLOT_RHAND)
r_item_use_skill $SKILL_MELEE

r_item_use_range 4
r_item_use_angle 8 //degrees
r_item_use_lifetime 0
r_item_use_cost 0
r_item_use_target $T_HORIZ
r_item_use_recoil -10
r_item_use_projeffect -1
r_item_use_traileffect -1
r_item_use_deatheffect -1
</code>

With that taken care of, we now need to spawn him with the item and equip them. In spite of how wolves normally attack, this will be equipped on his "paws". So open up his script and append the following onto the end. Also, we will place a '''location entity''' somewhere in the map near the wolf, he will wander around near it until he spots the player.

10.cfg
<code>
r_script_signal spawn [
r_action_wander self 0 96 0
r_additem self 6 1
r_equip self 6 0
]
</code>

==Addendum==

'''Debug flags'''

The debug variable is a set of flags, you can toggle most of them from the options menu under the game tab, but here they are, reproduced in full.

* 1 - World - draws misc information on the HUD and prints some information on the map stack
* 2 - Entity - draws entity pointers above head and prints when more are spawned and destroyed as well as their deaths and a few other things
* 4 - Configuration - prints what various properties were set to when loading definitions
* 8 - Projectiles - prints hit testing details and renders a pointer string over the projectile
* 16 - Script - informs you of most executed commands and any sent and received signals (when verbose)
* 32 - AI - draws waypoints and pritns any received commands
* 64 - I/O mainly lets you know what is being read from savegames
* 128 - Camera, draws cutscene information on the HUD
* 256 - Verbose, makes the rest spammier

'''Particles are everywhere!'''

If you're being overwhelmed by particles from rendering the waypoints, whether that involves them flickering, or simply bringing performance to a crawl, you can use '''maxparticledistance''' to adjust the draw distance, just don't forget to take note of its original value and change it back afterwards

=Part 6=

This section of the tutorial involves creating a fetch quest, mapflags and teleports

[[File:RPG_tutorial_map2.jpg|200px|thumb|rihgt|suggested layout for dungeon level]]

First up, before we get to the scripts, we are going to create an additional map set below tutorial1, the name of this will be tutorial2. If you are so inclined you can simply create the required geometry below the map, but this is to introduce you to mapflags and mutliple map setups.

We need at least 2 medium sized rooms, connected to each other, with the cavern on the first tutorial map leading into one of them. The first room will be the subject for part 7, the second will house the mcGuffin we will create for this part. The screenshot on the right has an example layout.

After that is done, our first order of business would be to add this to the list of maps for the tutorial game. Since we plan to create a special HUD for the map in the next part, it would be easiest for us if we can prohibit saving. Add the map as follows below the first map.

<code>
r_preparemap tutorial2 0 $MAP_NOSAVE
</code>

This now brings us to the most important, we need to define some means of getting in and out of the dungeon. We will need two triggers and scripts to do this. We will be using a special trigger flag that will make the trigger invisible and we will be using the collide script slot to trigger area transitions. If you like me, dislike that, use the interact slots instead. Spend some time first finding a model that fits the entrance to your cavern/dungeon well and would guarantee a collision before continuing. First off, let's define the scripts for our triggers.

11.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial2
]
</code>

12.cfg
<code>
r_script_signal collide [
r_teleport actor 0 tutorial1
]
</code>

The scripts would literally move whatever touches it to the specified map at teledest 0, but more on that later. We will now define our triggers.

1.cfg
<code>
r_trigger_name "Enter cavern"
r_trigger_script 11
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

2.cfg
<code>
r_trigger_name "Leave cavern"
r_trigger_script 12
r_trigger_mdl "ahab/castle_door"
r_trigger_flags $TRIG_INVIS
</code>

With that done, you can now spawn the triggers at their respective places. After doing that, spawn teledest ents with a tag of 0 outside the immediate area, so that the teleport command has a destination to place anything it teleports.

Our next step will be to make the mcGuffin, the mcGuffin in this case will be an item.

7.cfg
<code>
r_item_name "McGuffin"
r_item_description "This item is needed to advance the pl- er.. tutorial."
r_item_mdl "hirato/box/standard"
</code>

You will need to spawn this in the back of the dedicated room in the dungeon. After that is done, we only need to edit 2 more files, first up, open up variables,cfg.

You use this file to store variables and values you want to persist across sessions. So you want to use these to record the various choices the player has made, the things he has done and the status of all kinds of things in the world.

append this onto the end of variables.cfg
<code>
bobmcguffin = (r_global_new 0) //bob's quest to retrieve the mcguffin, 1 - have quest 2 - finished quest
</code>

We now only have Bob's dialogue left to go. We will provide different responses for the various states as well as set any variables that need be and remove any inventory items that need be.

We will need to change a fair bit of his script, So without further ado, open up his script and replace the dialogue with the following.

8.cfg
<code>
r_script_say "Hello, how are you doing" [ // 0 - it's good practice to number your entries
r_response "I'm well, yourself?" 1 //goes to dialogue #1
case (r_global_get $bobmcguffin) 0 [
r_response "Do you have any work for me?" 2
] 1 [
if (r_get_amount player 7) [
r_response "I brought you the mcGuffin" 4
] [
r_response "I brought you the mcGuffin" 6
]
] 2 [
r_response "Do you have any more work for me?" 7
]
r_response "Goodbye" -1 //closes the dialogue
]

r_script_say "I'm glad to hear it" [ // 1
r_response "Goodbye" -1
]

r_script_say "I need someone to go into the cave to the North-West of this valley and retrieve the mcGuffin, can you do that for me?" [ //2
r_response "You can count on me!" 3 [ r_global_set $bobmcguffin 1 ]
r_response "Maybe some other time" -1
]

r_script_say "Great! I'll be waiting for your return" [ //3
r_response "[End]" -1
]

r_script_say "Thank you for finding it, but I don't have a reward for you but I'd till very much like the mcGuffin." [ //4
r_response "[Give him the mcGuffin]" 5 [
r_remove player 7 1
r_givexp player 900
r_global_set $bobmcguffin 2
]
r_response "I think I'll hold onto it for now" -1
]

r_script_say "Thank you very much, I will never forget this" [ // 5
r_response "[End]" -1
]

r_script_say "Where is it?" [ //6
r_response "I must've forgotten it in the cave..." -1
]

r_script_say "No, but once again, thank you for getting this for me" [ //7
r_response "Farewell" -1
]
</code>

Congrats, you've made your first FedEx quest. I hope you're ashamed of yourself and will take this moment to reflect on your actions and produce quests with multiple paths and solutions that aren't simply get X of Y or kill X of Y ;)

==Addendum==

'''Mapflags'''

There are a variety of mapflags that will affect your ability to do things on the various maps, at present they are as follows

* F_VOLATILE - clears the map state when the player leaves, useful for dungeon levels
* F_NOSAVE - prevents saving whilst on the map - use sparingly
* F_NOMINIMAP - doesn't generate and display a minimap while this flag is active

'''Global Variable Tips'''

These are saved with your game and remain in a constant order and are all defined inside variables.cfg and they can only be integers. r_global_new returns the variable's index (ie, the first will return 0) and you should alias these return values to an easy to remember name that is short and as descriptive as possible. If you need to list more detailed information, do so in comments either before or on the same line.

You will want to increase the game/compat versions when you move/remove/add anything in here, serious breakage can occur

You should keep the names short and easy to type, for example, if we have a quest where you find a someone named Jane a bunch of apples, JaneApples and ApplesForJane would be some of the better names.

'''Journal'''

There is no journal at present but there will be in the future, you will want to record rumours, quest notes, deeds, obituaries and all kinds of other things in there. What you can do for now is make a book where the player can access all this information via dialogue.

=Part 7=

This part of the tutorial involves the creation of a basic logic puzzle to open a door.

We will create a 10 digit number pad of sorts, the player would need to interact with in a specific order to remove an obstacle we will place in the second area.

Our first order of business will be to define the variables we'll need to pull this off, we'll need two for the method we'll be using.

variables.cfg
<code>
keyprogress = (r_global_new 0)
keytest = (r_global_new -1)
</code>

Next we'll define the button's scripts. The scripts will set the keytest variable and will then call the "testkey" signal on the current map and propagate it to the door. We will define the door a bit later.

13.cfg
<code>
r_script_signal interact [
r_global_set $keytest 0
r_signal "testkey" self curmap 1
]
</code>

14.cfg
<code>
r_script_signal interact [
r_global_set $keytest 1
r_signal "testkey" self curmap 1
]
</code>

15.cfg
<code>
r_script_signal interact [
r_global_set $keytest 2
r_signal "testkey" self curmap 1
]
</code>

16.cfg
<code>
r_script_signal interact [
r_global_set $keytest 3
r_signal "testkey" self curmap 1
]
</code>

17.cfg
<code>
r_script_signal interact [
r_global_set $keytest 4
r_signal "testkey" self curmap 1
]
</code>

18.cfg
<code>
r_script_signal interact [
r_global_set $keytest 5
r_signal "testkey" self curmap 1
]
</code>

19.cfg
<code>
r_script_signal interact [
r_global_set $keytest 6
r_signal "testkey" self curmap 1
]
</code>

20.cfg
<code>
r_script_signal interact [
r_global_set $keytest 7
r_signal "testkey" self curmap 1
]
</code>

21.cfg
<code>
r_script_signal interact [
r_global_set $keytest 8
r_signal "testkey" self curmap 1
]
</code>

22.cfg
<code>
r_script_signal interact [
r_global_set $keytest 9
r_signal "testkey" self curmap 1
]
</code>

If you thought that wasn't boring enough, we now define the buttons themselves with similarly minor alterations, these should occupy slots 3 to 12 in the triggers directory, feel free to use a more appropriate model if you have one available.

3.cfg
<code>
r_trigger_name "0 Key
r_trigger_mdl "teleporter
r_trigger_script 13
</code>

4.cfg
<code>
r_trigger_name "1 Key
r_trigger_mdl "teleporter
r_trigger_script 14
</code>

5.cfg
<code>
r_trigger_name "2 Key
r_trigger_mdl "teleporter
r_trigger_script 15
</code>

6.cfg
<code>
r_trigger_name "3 Key
r_trigger_mdl "teleporter
r_trigger_script 16
</code>

7.cfg
<code>
r_trigger_name "4 Key
r_trigger_mdl "teleporter
r_trigger_script 17
</code>

8.cfg
<code>
r_trigger_name "5 Key
r_trigger_mdl "teleporter
r_trigger_script 18
</code>

9.cfg
<code>
r_trigger_name "6 Key
r_trigger_mdl "teleporter
r_trigger_script 19
</code>

10.cfg
<code>
r_trigger_name "7 Key
r_trigger_mdl "teleporter
r_trigger_script 20
</code>

11.cfg
<code>
r_trigger_name "8 Key
r_trigger_mdl "teleporter
r_trigger_script 21
</code>

12.cfg
<code>
r_trigger_name "9 Key
r_trigger_mdl "teleporter
r_trigger_script 22
</code>

We will not get to the fun part! defining the actual door itself (hooray!). Like in every other instance, we will define the script first. The door's script will be as follows, it need to test and increment the global variables we've defined earlier.

23.cfg
<code>
key = [ 3 1 3 3 7 ] //change as appropriate
keylen = (listlen $key)

r_script_signal testkey [
if (< (r_global_get $keyprogress) @keylen) [
if (= (at [@@@key] (r_global_get $keyprogress)) (r_global_get $keytest) [
r_global_set $keyprogress (+ (r_global_get $keyprogress) 1)
] [
r_global_set $keyprogress 0
]
if (= (r_global_get $keyprogress) @@keylen) [
r_trigger self
]
]
]
</code>

We will now make the trigger itself, like with the last step, choose a model of appropriate size to block the passage to the mcGuffin

13.cfg
<code>
r_trigger_name "Heavy door"
r_trigger_mdl "ahab/castle_door"
r_trigger_script 23
</code>

==Addendum==

'''a guiding hand'''

Depending on the puzzle and its difficulty, you should strive to give the player a few hints to solve it. You should avoid giving the player the answer but you should give the player some audio or visual feedback based on his actions.

Take our above puzzle for example, we have no idea if the combination we have entered is even correct apart from the door opening after interacting with the triggers. In addition, trying every 5 digit combo to get the example combination can take as many as 100000 attempts.

For a puzzle like that, it is unreasonable to just expect the player to figure out the answer himself without a few hints. Short of giving the player the answer, we could perhaps tell him the digits but in a wrong order, or perhaps give him a mnemonic he has to decipher to get the answer.

=Extras=

* [http://www.sendspace.com/file/cu341n Finished product] - Note, sandbox 2.7.1 or newer is required -> link is currently dead!

RPG script

2012-04-17T10:41:41Z

Kddekadenz: /* Signals */

=References=
References are stored separately of cube script and are defined as a stack of hashtables that can be arbitrarily incremented and decreased. The depth is typically 1 unless a script is executing or things are being run inside a r_stack block.

References are the system that exposes a lot of functionality as well as providing a relatively fast and type-safe means for creators to script assorted interactions in their games.

As a general rule, a reference must be defined (or registered) before it can be set or searched for. There are two ways to register a reference. The first is using '''r_registerref''' and the second using '''r_registertemp'''. Both behave exactly the same except for one difference, '''r_registertemp''' only searches the top level for a matching reference as opposed to the whole stack, otherwise they both create one at the top level if one isn't found. Due to this behaviour, you can shadow variables quite easily and painlessly and allows us to use self and actor as reference for just about every script call.

The references can reference just about anything in the RPG, the current official list is as follows. Note that volatile references are cleared at the start of every update due to the volatile nature of what they reference.
* Critters
* Items
* Obstacles
* Platforms
* Triggers
* Inventory
* Equipment (volatile)
* Map
* Victim Effect (volatile)
* Area Effect (volatile)

In addition the following list should be considered reserved, you may use them for other purposes but we really do not recommend this for obvious reasons.
* player - the player
* curmap - the current map
* hover - the current hover target
* talker - who the player is currently talking to
* actor - generally something that sent a signal to the entity in the self reference
* self - something executing a script, typically due to to receiving a signal fro mactor

=Signals=

Nearly all scripts in the RPG are defined as a signal to either the script on the mapscript subtypes. The signals can have just about any name, there are several loosely reserved names the engine will call periodically but the creator has completely free reign on what he wants to name his signals and what he wants and when alongside those the game call.

Signals are sent to everything by default unless a specific target is specified. Signals called periodically by the game are as follows
* update - sent to everything every update
* collide - sent to every pair of entities that collided in an update
* hit - sent when something is hit by another's attack
* interact - typically sent when you press the E key while having a hover target
* death - sent to an entity when it does
* level - sent to an entity when it gains a level
* equip - send to the item when an entity equips it
* load - sent to the map when it's initialised
* spawn - sent to an entity when it's created
* attack - sent when an entity attacks

This list is subject to change in the future

=Context sensitive values=

When some conditions are met or certain signals are sent, global variables are set for it to use.

'''hit signal'''

friendly - notes whether or not the attack was friendly

'''script/signal status effect'''

=Commands=

Tutorials List

2012-04-13T16:43:42Z

Kddekadenz: /* Other useful tutorials */

== Getting, Installing and opening Sandbox ==

* [[Downloading Sandbox]]
* [[Installing Sandbox]]
* [[Running Sandbox]]
* [[development|Obtaining the development version]]

== Modules ==
* [[FPS|FPS - First Person Shooter (default)]]
* [[SSP|SSP - Side Scrolling Platformer]]
* [[RPG|RPG - Role Playing Game]]
* [[MovieCube|MovieCube - Machinima Tool]]
* [[Vehicle Simulator]]
== Learning the editor basics ==

* [[Map Editing Basics]]
* [[How to place 3D grass]]
* [[How to add lava, water, glass and other materials to your map]]
* [[How to make invisible boundaries]]
* [[Tips on making a good map]]

== Buildings ==

* [[How to make sloped roofs]]
* [[How to make secret doors, walls & floors]]
* [[How to make 1-way windows only you can see out of]]
* [[How to make 1-way doors]]
* [[How to create a hollow tower/tube]]
* [[How to make stairs you could walk up]]
* [[How to create set of glass stairs]]
* [[How to make a TV]]
* [[How to make various window shapes]]
* [[How to create a spiral staircase]]
* [[How to make a pyramid/four-sided sloped roof]]

== Lighting and Particle effects ==

* [[How to add various lighting]]
* [[Lighting|How to light a map properly]]
* [[Tips to make a night time map]]
* [[Tips to make a morning map]]
* [[Tips to make a sunset map]]
* [[How to add particle effects]]
* [[How to create snow or rain]]
* [[How to put fog to a map]]
* [[Useful lighting commands]]

== Terrain editing ==

* [[How to create mountains, ponds, and oceans]]
* [[How to transfer parts of a map to a new one]]
* [[How to make a forest]]
* [[How to make a cave]]
* [[How to make a realistic river]]
* [[How to make a swimming pool]]
* [[How to make a fountain]]
* [[How to create smooth curvy pathways]]
* [[How to create fields with flower patches]]
* [[How to create a camp fire and fireplace]]
* [[How to make a hollow pyramid]]
* [[How to make a bumpy road]]
* [[How to make various types of fences]]
* [[How to make a nice waterfall]]
* [[How to edit terrain properly]]
* [[How to fix bad terrain or geometry errors]]
* [[How to make railings]]

== NPC-s ==

* [[Creating a shop script]]
* [[How to make characters talk with text pop-up windows]]
* [[How to make characters talk with a voice recording]]
* [[How to make characters give you quests]]
* [[How to add bots and train them]]
* [[Ultimate Simple Script Guide, Part 1]]
* [[Ultimate Simple Script Guide, Part 2]]

== Importing models to Sandbox ==

* [[Blender to Sandbox]]
* [[Wings3D to Sandbox flash tutorials]]
* [[Importing .OBJ files]]
* [[Mapmodels|Loading and adding mapmodels]]
* [[How to add new models]]

== Textures ==

* [[Glowmaps]]
* [[Adding custom textures to a new map]]
* [[Adding custom textures with normal maps]]
* [[How to make new textures]]
* [http://www.leighvanderbyl.com/pdf/texturing.pdf Texturing for Dummies ]
* [http://www.cgsociety.org/index.php/CGSFeatures/CGSFeatureSpecial/the_top_ten_tips_of_texturing Top Ten Tips of Texturing]
* [http://forums.cgsociety.org/showthread.php?t=373024 Hard Surface Texture Painting]

== Scripting tutorials ==

* [[Menu Editing|How to modify the menu]]
* [[making picked up items visible in your inventory]]
* [[How to make a trigger load another map]]
* [[Cubescript]]
* [[Creating easy spells]]
* [[Removing Editmode]]
* [[Making Echoes]]
* [[Adding Custom Skyboxes]]

== Maptitle and authors ==

* [[How to add map title and author]]
* [[How to change color of text in maps welcome message]]

== Multiplayer tutorials ==

* [[How to host a coop edit session over the internet]]
* [[How to host a persistent world in Sandbox over the internet]]
* [[How to monitor your dedicated server without being in it]]

== Other useful tutorials ==

*[[Guide to a good game]]
*[[Editing the wiki]]
*[[Customizing Sandbox]]
*[http://forum.sandboxgamemaker.com/viewtopic.php?f=24&t=1493 Copyrighting your content]
*[http://quadropolis.us/node/2328 Gridwork]
*[[Adding custom songs to Sandbox]]
*[[Creating 3D models with PAS]]

== Unsorted tutorials ==
* [[Transfering your map from one sandbox version to another]]
* [[How to make items that can be picked up]]
* [[How to make moving doors and platforms in single player mode]]
* [[How to add your own music]]
* [[How to create skymaps]]
* [[How to create lens flares]]
* [[How to create a slide]]
* [[How to create a trampoline]]
* [[How to create electric fences]]
* [[How to create warp speed tunnels]]
* [[How to create climbable ladders and vertical walls]]
* [[How to create hidden teleports]]
* [[How to create spinning palm trees]]
* [[How to capture screen shots and videos]]
* [[How to make ramps, bridges, and angles]]
* [[How to change gravity]]
* [[How to save a map properly]]
* [[How to change textures in your map]]
* [[How to add creatures]]
* [[How to add new colors of creatures and map models]]
* [[How to add more player character models]]
* [[How to make an endless slide]]
* [[How to make a robochimp throw you into the air]]
* [[How to make a snowman]]
* [[How to make a boat]]
* [[How to resize map models and textures]]
* [[How to add projectiles to your game]]
* [[How to automatically save your map every x number of minutes]]
* [[How to make a sphere shapes in 'edit mode']]
* [[How to make curved shapes in 'edit mode']]
* [[How to create curved glass]]
* [[How to make a water slide]]
* [[How to make triggered elevators/platforms]]
* [[How to get a mapsize greater than 16]]

== Sandbox Related ==
* [[How to contribute to Platinum Arts Sandbox]]
* [[Tips on creating content]]
* [[Models Vs. Geometry]]
* [[Where to find inspiration]]

----

* [[Creators of these tutorials]]

Main Page

2012-04-13T16:41:23Z

Kddekadenz: /* Tutorials */

'''Platinum Arts Sandbox Free 3D Game Maker''' is a 3D game maker based on the Cube 2 engine that allows users to quickly and easily create and edit their own worlds in game, even cooperatively. It is free, open-source, and easy to use for Kids and Adults. Sandbox logo by [http://sashazavisha.deviantart.com/art/young-creator-120946941 sashaZavisha].

<div style="width:49%;float:left;">

== General information ==

* [[Platinum Arts Sandbox|About Platinum Arts Sandbox]]
* [http://SandboxGameMaker.com Project homepage]
* [[FAQ]]
* [[Contact The Team]]
* [[cmdline arguments|Command line Arguments]]
* [[packaging guide|The Packaging Guide]]
* [[server list|List Of Sandbox Servers]]

== Installation ==
* [[Installing Platinum Arts Sandbox]]
* [[Compiling the source code]]
* [[package managers|Some Notes for package managers]]

== Development ==

* [[bug reports|Bug Reports]]
* [[Coding Style]]
* [[Contributing]]
* [[development|Obtaining the development version]]
* [[Todo|To do list]]
* [[content request| Content Request - Help us out!!]]

== Kid Friendly RPG ==
* [[Concept Document]]
* [[Brainstorming area]]

== Master Chef Ogro 2 ==
* [[Brainstorming]]

== Undercover Kids Game ==
* [[To Do List]]

</div>
<div style="width:49%;float:right;">

== Getting started ==

* [[Map Editing Basics]]
* [[Mapping Taboos]]
* [[Beginner's video tutorials]]
* [[Good free programs for Sandbox]]

== Advanced topics ==

* [[Cooperative Editing]] (General Server set up)
* [[Cooperative Editing 2]] (Easier way using Hamachi)
* [[Adding Models to Sandbox]]
* [http://sandboxgamemaker.com/platinumartssandboxeditref.html Editing Reference Guide]
* [http://sauerbraten.org/docs/models.html Model Reference Guide]
* [[Configuration Reference Guide]]
* [[Cubescript]]
* [[Menu Editing]] ([[New menu editing|newui]])
* [[map_config|Map Configuration]]

== Example Modules ==

* [[FPS|FPS - First Person Shooter (default)]]
* [[RPG|RPG - Role Playing Game]]
* [[SSP|SSP - Side Scrolling Platformer]]
* [[MovieCube|MovieCube - Machinima Tool]]
* [[Vehicle Simulator]]

== Tutorials ==
*[[Tips on Making a Good Map]]
*[[Tutorials List | Text Tutorials List]]
*[[Video Tutorials List]]

== Other ==
*[[Soundtrack]]

Creating 3D models with PAS

2012-04-13T16:35:45Z

Kddekadenz:

1) create a newmap 
2) delete everything 
3) create your desired model 
4) use the command '/writeobj name' to export your model 
5) optional - open the model with a 3D modeling programm and edit it

Creating 3D models with PAS

2012-04-13T16:34:21Z

Kddekadenz: Created page with '1) create a newmap 2) delete everything 3) create your desired model 4) use the command '/writeobj name' to export your model 5) optional - open the model with a 3D modeling prog…'

1) create a newmap
2) delete everything
3) create your desired model
4) use the command '/writeobj name' to export your model
5) optional - open the model with a 3D modeling programm and edit it

Main Page

2012-04-13T16:31:00Z

Kddekadenz: /* Tutorials */