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

File:Pas to blender4.jpg

2012-11-18T00:02:18Z

Hirato:

File:Pas to blender3.jpg

2012-11-18T00:00:41Z

Hirato:

File:Pas to blender2.jpg

2012-11-17T23:59:44Z

Hirato:

File:Pas to blender1.jpg

2012-11-17T23:58:38Z

Hirato: moved File:Blender to pas1.jpg to File:Pas to blender1.jpg

File:Blender to pas1.jpg

2012-11-17T23:58:38Z

Hirato: moved File:Blender to pas1.jpg to File:Pas to blender1.jpg

#REDIRECT [[File:Pas to blender1.jpg]]

File:Pas to blender1.jpg

2012-11-17T23:57:22Z

Hirato:

Soundtrack

2012-08-26T16:46:33Z

Hirato:

A list of songs used in Platinum Arts Sandbox. From 2.7.1 and on, Sandbox uses music from Cork279, a forum member. Feel free to add more information and improve the page

=From 2.7 and Before=
*This list is found in PlatinumArtsSandbox2.7/packages/music/License

==Artificial-World.ogg==
*Composed by mindthings
*Downloaded from http://www.newgrounds.com/audio/listen/119771
*license CC-BY-NC-SA

==Home.ogg==
*Composed by Farmin
*Downloaded from http://www.newgrounds.com/audio/listen/102106
*license CC-BY-NC-SA

==Last-Flight.ogg==
*Composed by Reasoner
*Downloaded from http://www.newgrounds.com/audio/listen/131755
*License CC-BY-NC-SA

==Sense-of-Happiness.ogg==
*Composed by Developer
*Downloaded from http://www.newgrounds.com/audio/listen/123025
*License CC-BY-NC-SA

==Transition.ogg==
*Composed by Puggin
*Downloaded from http://www.newgrounds.com/audio/listen/136436
*License CC-BY-NC-SA

==traveling_minstrels.ogg==
*Composed by Mattias Westlund
*Taken from the Battle For Wesnoth Soundtrack

==Rusted-Toys.ogg==
*Composed by Mo-Tech
*Downloaded from http://www.newgrounds.com/audio/listen/96193
*License CC-BY-NC-SA

==Island-Shores-at-Night.ogg==
*Composed by SBB
*Downloaded from http://www.newgrounds.com/audio/listen/79665
*License CC-BY-NC-SA

==Silent-Tears.ogg==
*Composer: Calvin Briggs (Dj-Flux)
*Download location: http://www.newgrounds.com/audio/listen/186589
*license CC-BY-NC-SA

==Valley_of_the_Wind.ogg==
*Composer (DJ) Bjra
*Download Location: http://www.newgrounds.com/audio/listen/251469
*license: CC-BY-NC-SA

==losingyourlogic.ogg==
*Composer: Howard Lockward
*Download Location: http://www.newgrounds.com/audio/listen/293208
*license: CC-BY-NC-SA
**Not used in any versions, but included in 2.7. Information found under PlatinumArtsSandbox2.7/packages/music/Song License.txt

=From 2.7.1 and On=
*All music was created by Cork279, aka "R-Y-S-E". See more of his work on [http://soundcloud.com/r-y-s-e Soundcloud].
*All music is released under a CC-BY license.
==Agent.ogg==
==Blue.ogg==
==Brilliance.ogg==
==Jingle.ogg==

==Secrets.ogg==
==Taunt.ogg==
==Truth.ogg==
==Wild.ogg==

Cubescript

2012-08-06T13:15:32Z

Hirato: delayed evaluation and early termination of logical statements

Cubescript is the scripting language utilised within the sauerbraten/cube2 engine. it is used to set aliases, variables, create binds and generate the menu.

=Writing in Cubescript=

==Aliases==

The brunt of cubescript is concerned with Aliases. Aliases have 3 basic uses.
* store lists and values for extended periods of time
* store temporary lists and values
* grouping a set of commands which are useful when combined

There are two ways to declare an alias. You can do it via infix notation, or by using the alias command. It should be noted that aliases are the exception to the rule, infix notation is only available for creating aliases.

A VERY important note, alias specific operations are available to aliases only. this means builtin variables can't be set or overridden through alias, =, pop and push (among others).

<code>
//command
alias myalias [1]

//infix variant
myalias = [1]
</code>

===executing aliases===

To execute an alias, you execute it like any other command. if I had an alias named '''myalias''', I would simply invoke ''''/myalias''' to execute it.

These aliases also have access to a class of special aliases. Those are the temporaries in which arguments are stored. There's also a useful variable named 'numargs' which tell you how many arguments were provided. The aliases containing the arguments are named arg. they are numbered and enumerated, starting from 1, so you'd use $arg1 to access the first argument. This does not start at 0, since arg0 is the command's name (arg0 is also not defined.. ever, nor included in numargs).

<code>
//prints all arguments to screen, one by one
//see the other comments for an explanation

print = [ //declares an alias named print
loop i $numargs [ //loops $numargs times, setting i to the current iteration
echo (getalias (concatword arg (+ $i 1)) //gets the value of the arguments, by accessing $arg1 $arg2 $arg3....
] //close loop
] //close print alias
print I like unicorns //should print I like unicorns on 3 separate lines
</code>

===push and pop===

Push and pop used to be two separate instructions, but since the advent of the new Cubescrpt interpreter/compiler (2.6.1), they have been merged into a single instruction. The syntax for this singular stack manipulation command is as follows.

push variable value body

The stack is automatically popped after execution

<code>
myalias = "candy"
push myalias "lollipops" [
echo $myalias
]
echo $myalias

//expected output
//lollipops
//candy
</code>

==Syntax==

Cubescript is not your typical scripting language. Cubescript is not the most flexible, or the best language, but it more than adequate for our needs and purposes. Cubescript draws its main inspiration from quakescript and from Lisp. It is therefor said that Cubescript contains many "Lispisms". Below is a summary of notable features/quirks.

* comments are denoted by //
* both newlines and ; denote the end of a call.
* newlines will automatically close of any strings you may have forgotten to. (you should not rely on this)
* substitutions are done through the use of $ and @ tokens, (See below)
* everything is a function which may take arguments. With the exception of setting an alias, infix notation does not exist
* there are no arrays or vectors, only lists.
* most implementations have a 25 word limit. This means commands can be invoked with up to 24 arguments

one liner example

<code>
alias hi [say "hi"; sleep 5000 [say "Hi again"]]
</code>

multi liner example

<code>
alias hi [
say "hi"
sleep 5000 [
say "Hi again"
]
]
</code>

it's obvious what the above code does, it'll make your character say hi, and wait 5 seconds before saying hi again.

indenting is done in levels, the Tabulator (TAB) key is usually used to indent the text. while not necessary, it tends to make it bigger, and more legible as seen in the above example (when you get to big stuff, you'll thank yourself for indenting it.

As a rule of thumb, pretty much only [ increases the indentation level. Also note, ", ] and ) can close each other, so make sure you close them off properly

==containers==

Containers in cubescript are of 3 specific types, "", () and [] - all of these have significant differences in operation and use

==="" container===

"" containers are used to store things EXACTLY as they are written, with a few small exceptions - in-text commands which are denoted by a preceding ^. They are as follows

* ^f#
** ^f# is used to colour text. # must be replaced by either a number or a capital letter (A-Z). r and s are special control characters which will restore and save the text's current colour respectively.
* ^n
** insert a '\n' character (newline/linefeed)
* ^t
** inserts a '\t' character (tabulator)
* ^"
** inserts a quote (")

===() container===

() containers are used mainly for logic/arithmetic operations. They are usually nested inside [] blocks, and unless they are nested inside []'s they're permanently substituted with their results.

For example - the following will turn into an infinite loop. The condition is initially evaluated and substituted with one and since 1 can never = 0, it's true forever more

<code>
i = 0
while (= $i 0) [i = (+ $i 1)]
</code>

the following code on the otherhand is devoid of such issues. Being nested inside the [] means it's not substituted and evaluated each cycle

<code>
i = 0
while [= $i 0] [i = (+ $i 1)]
</code>

===[] container===

This container is used for nesting, deferring execution of it's contents, deferring calculations and substitutions of () containers, and substitutions of aliases/variables written with a @ prefix (note several levels are needed to achieve this). [] containers are also the ONLY container capable of spanning multiple lines.

This is the most used container and due to it's properties, is ideal for creating aliases.

generally statements in cubescript can't span multiple lines. If you should use this container and occupy several, the execution of the prior command continues exactly where this container finished off. This can be demonstrated with an if statement.

<code>
if 1 [
do
stuff
] [
do
other
stuff
]
</code>

Also on the subject of if statements, logical operators like && and || in fact execute its arguments iteratively. This allows us to make use of [] to delay evaluation of conditionals. As we learned in the () section, when an instance is encountered it is immediately executed and substituted with its result. This method also allows us to terminate these logical checks early if some exit condition is met (ie, a false result is encountered with &&) without evaluating all the conditions)

<code>
var1 = 2
var2 = 3
var3 = 10

//a traditional if with multiple conditions
if (&& (= $var1 2) (>= $var2 4) (& $var3 2)) [] []

//This is in fact interpreted as follows; since () denotes immediate substitution
//While early termination does work, all of the conditionals are evaluated, rendering it somewhat moot.
if (&& 1 0 2) [] []

//We can rewrite this to make proper use of delayed evaluation and early termination as follows
//While this example doesn't show it, like C this is very useful if you need an earlier condition to be true
//for subsequent conditions; ie C: if(ptr && ptr->val) {} which terminates early if ptr is NULL.
if (&& [= $var1 2] [>= $var2 4] [& $var3 2]) [] []
</code>

==substitution==

there are two principle ways of substituting values in cubescript, the first is through the use of $ tokens, the second is through the use of @ tokens.

a very simple example:
<code>
myalias = 5
echo $myalias
</code>
myalias is substituted into the echo statement, so you should see 5 printed to the top-left of the screen

using the @ token would have also resulted in the same behaviour
<code>
myalias = 5
echo @myalias
</code>

There's a big difference between the two, the @ token can be used to concatenate stuff together, $ can't. @ is also substituted immediately up to the first level of nesting. (this can be incremented by using additional @ tokens, ie @@ for 2 levels of nesting). Do take note that too few @ tokens may cause a substitution to happen too late, and too many may likewise cause it to happen too early or cause other weird and subtle issues.

'''An example of use in a level 1 nest'''

<code>
myalias = "I am awesome"
mymenu = [guitext @myalias]
</code>
if you were to type /echo $mymenu, it should read: guitext "I am awesome"; using the $ token on the other hand

<code>
myalias = "I am awesome"
mymenu = [guitext $myalias]
</code>
typing /echo $mymenu should produce: guitext $myalias

'''An example of concatenation'''

as i mentioned, @ also allows you to concatenate stuff together, which could result in shorter and simpler scripts. It should be noted that this can also result in extreme obfuscation
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [ do [
echo $myalias@i
]]
</code>
this should print 5, 3.1415 and 2.481 respectively

the purely $ token equivalent
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [
echo (getalias (concatword myalias $i))
]
</code>

'''Lookup of a Lookup'''

There are two ways to look up multiple things; the first is by encasing it inside 'getalias', the second involves using multiple lookup tokens. There is a caveat with the second method, while it works on more types, it's only available in sandbox as of 2.6.1.

All 3 of the below examples should print "victory!"
<code>
alias1 = "alias2"
alias2 = "alias3"
alias3 = "victory!"

//the first method
echo (getalias (getalias $alias1))

//the second method; 2.6.1
echo $$$alias1

//to show compatibility with @
do [
echo $$@alias1
]
</code>

==Branching/Decisions==

Decisions are based on 6 key commands, '''if''', '''?''', '''cond''', '''case''' (integer), '''casef''' (float) and '''cases''' (string). There are also other ways to do this. For example you might be able to easily query something about an object, where it's obviously unique. You would then execute an alias whose name has this unique bit attached onto the end. This is an advanced method and is generally not recommended.

===if and ?===

Arguments: Cond True False

Unlike most other languages, cubescript's '''if''' contains an implicit else, in short we do not have an else statement. The provided condition is true if it ends up as a series of alpha numerics, or in the case of a number, as a value other than 0.

<code>
myalias1 = 5
myalias2 = "woot"

//if else-if else
if $myalias1 [
echo "myalias1 is true"
] [
//this shows the alpha numerics case
if $myalias2 [
echo "myalias1 is false and myalias2 is true"
] [
echo "myalias1 is false and myalias2 is false"
]
]
</code>

'''?''' acts exactly the same way, but there's one HUGE difference. '''?''' does not execute the chosen result.

<code>
//an example of where ? can be used where if would fail
items = 1
echo (format "You are carrying %1 item%2." $items (? (= $items 1) "" "s"))
</code>

===cond===

basically you provided a several pairs of arguments, the first half of the pair is the condition, and the second is the result. To put it in a programming perspective, this is like creating a long line of if else's together. Execution stops when the first condition is matched. Should you place several conditions where more than one may be true at any one time, only the first will be executed.

The following example assumes you have a light entity selected

<code>
lightstrength = [
cond [< (ea 0) 0] [
echo "It's like a black hole!"
] [= (ea 0) 0] [
echo "Blindlier than science!"
] [< (ea 0) 8] [
echo "It's weaker than Billy's night light!"
] [< (ea 0) 32] [
echo "Nice night light you got there"
] [< (ea 0) 96] [
echo "It's like a lamp, but it's not a lamp"
] [< (ea 0) 512] [
echo "By Jove! I can actually see the ground!"
] [>= (ea 0) 512] [
echo "Dark places are icky, don't you agree?"
]
]
</code>

===case===

This works similar to switches in most programming languages. The biggest difference is that you can't break out, nor evaluate multiple cases (aka, fallthroughs).

The first argument tells it which variable to use. The following arguments are given in pairs, the first half is the state, the second is the result.
If the state is a null type, it is considered the default case. The easiest way to generate a null type is to use ()

The following example requires a particles entity to be selected, it will print out what type it is. Do note that this example exceeds the 25 word limit.

<code>
parttype = [
pname = ""

case (ea 0) 0 [
pname = "Fire and Smoke"
] 1 [
pname = "Fire"
] 2 [
pname = "Smoke Plume"
] 3 [
pname = "Smoke"
] 4 [
pname = "Fountain"
] 5 [
pname = "Explosion"
] 6 [
pname = "Meter"
] 7 [
pname = "Vs Meter"
] 8 [
pname = "Text"
] 9 [
pname = "Flare"
] 10 [
pname = "Lightning"
] 11 [
pname = "Fire"
] 12 [
pname = "Smoke"
] 13 [
pname = "Water"
] 14 [
pname = "Snow"
] 15 [
pname = "Leaves"
] 32 [
pname = "Lens Flare"
] 33 [
pname = "Fixed Size Lens Flare"
] 34 [
pname = "Sparkly Lens Flare"
] 35 [
pname = "Sparkly Fixed Size Lens Flare"
] () [ //default
pname = "A very pretty albeit unsupported particle"
]

echo The particle you have selected is of type: $pname
]
</code>

===Naming===

another way of doing decisions/branches is to use paths with different names. This has limited usage though. in short it requires you to query some information to concatenate onto another word, which you would then execute. There are exceptions. Other than the number of results you can query, there is no limit here. A handy trick is to have several results execute the same alias, though this requires that they differ only slightly at most in operation.

<code>
//This example demonstrates the exception
//it requires you to have an entity selected
//This will conflict with showquickgui
newgui "particles" [guitext "It's like a random series of nothing"]
newgui "light" [guitext "SHINY!!!!"]
newgui "jumppad" [guitext "boing!"]

identify = [showgui (et)]
</code>

<code>
//shows a more standard example, at present this is exclusively used by edithud (see stdedit.cfg)
//this also requires you to have an entity selected.
identlight = [echo "it's so bright..."]
identdynlight = [identlight] // to demonstrate how different results can execute the same script
identjumppad = [echo "boing? boing!"]
identparticles = [echo "Please don't change it to a lens flare!"]

identify = [ if (enthavesel) [ident@(et)] [echo Select an entity first!]]
</code>

==Lists==

Ordered lists are the closest cubescript has to the likes of arrays. Their declaration is identical to any alias, as they are simply items in a string separated by white space. Using [] is recommended as the container of choice, since it allows you to use "" to include multi-word items in a list as a single unit as well as define the list over multiple lines. "" can also be used to define lists. An example can be inspected below.

<code>
//declares 2 equivalent lists of 3 elements
mylist1 = [one two "three four"]
mylist2 = "one two ^"three four^""

//prints the 3rd element
echo (at $mylist 2)
</code>

'''loops'''

There are at least 2 ways to loop through a list. The first method involves the use of looplist to iterate over it and the second the use of listlen to determine the list's length. The difference between using looplist and listlen is that you will not have a reliable way of determining an element's index and won't have to manually fetch the element from the list. Basically looplist is faster at the cost of some information and should be used in all cases where the index does not need to be known.
An example can be inspected below.

<code>
mylist = [
0
1
3.14159265359
2.71828182845
sqrt(-1)
1 //to demonstrate that the index cannot be determined reliably with looplist
]

//demonstrates looplist
looplist var $mylist [
echo number (listfind item $mylist [strcmp $var $item]) : $var
]

//demonstrates a loop + listlen combo
loop i (listlen $mylist) [
echo number $i : (at $mylist $i)
]
</code>

'''concatenation'''

Concatenation is pretty simple, albeit not very efficient. It is basically, setting the list to itself plus the additional item. This is of course best achieved through the concat commands.

<code>
mylist = [1 2 3 4 5 6 7 8 9 10]

//using concatword
mylist = (concatword $mylist " " 11)

//using format
mylist = (format "%1 %2" $mylist 12)

//using concat - we're also preparing it for pretty list
mylist = (concat $mylist 14)

//pretty list does add an item onto the list, but it changes the format dramatically and the new item is placed before the end
//it is ideal more so for making things pretty for presentation than concatenation
mylist = (prettylist $mylist 13)

//should print 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 14
echo mylist is $mylist
</code>

concat returns everything given to it as a singular item, spaces and all. Concatword ignores spaces and ""'s must be explicitly provided. Concat is therefor ideal to add lists together.

<code>
mylist1 = [1 2 3 4 5]
mylist2 = [6 7 8 9 10]
mylist3 = [11 12 13 14 15]
mylist4 = [16 17 18 19 20]
mylist5 = [21 22 23 24 25]
mylist6 = [26 27 28 29 30]
finallist = ""

//how concatword merged three lists
finallist = (concatword $mylist1 " " $mylist2 " " $mylist3)

//concat unlike the above does not require
finallist = (concat $finallist $mylist4 $mylist5 $mylist6)

echo (prettylist $finallist)
</code>

'''finding'''

there are two ways to find things, the first is to use listfind, and the second is to loop through the list. Both are demonstrated in the example below

<code>
mylist = [
"Jack"
"Jane"
"Joseph"
]

//This is an example of looking for a single element, note that this variant of...
//strcmp unlike its C counterpart returns 1 when strings are equal
//in this example, a 0 should be printed at the top of your screen - listfind returns the index
echo (listfind f $mylist [strcmp $f "Jack"])

//In this example, -1, as Jill is not in the list
echo (listfind f $mylist [strcmp $f "Jill"])

//in this example, we want to find anything which contains an e and add it into a list
results = ""
looplist var $mylist [
if (>= (strstr $var "e") 0) [
results = (concatword $results "^"" $var " ^"")
]
]

//this should print: Jane Joseph
echo $results
</code>

=List of commands=

==General==

The following commands are quite often used in a lot of scripts.

* alias N B
** creates an alias named N with body B, the intext version is denoted as N = B (equivalent to alias N B)
* at S I
** returns the Ith element in string S, note that counting starts from 0. If it's out of range, "" is returned
* getalias A
** returns the value of A. this also does not produce a warning should an alias be undeclared, nor complains when fetching built in variables.
* if C T F (F is optional)
** if condition C is true, execute T, otherwise F is executed
* listlen S
** returns the amount of elements in list S
* loop V N B
** loops N times, and aliases the current iteration to V; B is executed every iteration.
* result S
** returns the string, useful when aliases need to be executed
* rnd N L
** chooses a random number between 0 and N-1 (inclusive). L sets the lower limit. eg rnd 12 7 will return either 7 8 9 10 or 11
* sleep N B
** executes B after a delay of N milliseconds. NOTE: even if N is <= 0, it'll still wait till the next frame before executing it
* while C B
** executed B while C is true. NOTE: surround C in a [] container, or you risk an infinite loop due to the condition not being reevaluated.

==Map Configuration==
'''''ONLY APPLIES TO FPSGAME'''''

The following commands are useful in level only aliases

*triggerstate
*level_trigger
**level trigger is invoked as level_trigger_1 = [] as an example, the end number is the 4th number in the mapmodel's strings
*level_base
**Used to give bases names in capture mode. This is unfortunately unused in PAS

==Binds==

The following commands are useful in binds.

*onrelease

==Gui Creation==

For newui, please see [[new menu editing]]

These commands are used to create various menus.

* cleargui
* guibar
* guibutton
* guicheckbox
* guifield
* guikeyfield
* guiimage
* guilist
* guirolloveraction
* guirollovername
* guislider
* guilistslider
* guinameslider
* guistayopen
* guitab
* guitext
* guititle
* guistrut
* newgui

==Comparisons==

The functions here can change the values, or return a logical comparison
for all intents and purposes, the C version of booleans apply here; values not equal to 0 are true - and functions that return true return 1

===Integer Arithmetic===

* + A B
** returns the value of the numbers added together
* <nowiki>*</nowiki> A B
** returns the result of multiplying A and B
* - A B
** returns the value of A - B
* = A B
** returns true of the two are equal
* != A B
** returns true if the two aren't equal
* <nowiki><</nowiki> A B
** returns true if A is less-than B
* <nowiki>></nowiki> A B
** returns true if A is greater-than B
* <nowiki><=</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* ! A
** if the argument is false, it returns true
* &&
** returns true if all arguments are true
* ||
** returns true it at least one argument is true
* div A B
** returns the value of A divided by B
* mod A B
** returns the modulus of the two arguments
* min
** returns the lowest valued argument of all provided arguments
* max
** returns the highest valued argument of all provided arguments

===Bitwise Integer Operations===

* ^ A B
** returns the value of A xor B ie (^ 8 4) is 12 - (^ 12 4) is 8
* & A B
** returns the value of the bits both A and B have
* | A B
** returns the value of the bits either A or B have
* ~ A
** returns the inverted bitwise version of A ie (& (~ 128) 255) is 127
* ^~ A B
** xor;s the arguments after applying an inversion on B
* &~ A B
** and's the arguments after applying an inversion on B
* |~ A B
** or's the arguments after applying an inversion on B
* <nowiki><<</nowiki> A N
** shifts A N bits
* <nowiki>>></nowiki> A N
** shifts A -N bits

===Floating Point Arithmetic===

Generally these just have an -f suffix

* +f A B
** returns the value of the numbers added together
* <nowiki>*f</nowiki> A B
** returns the result of multiplying A and B
* -f A B
** returns the value of A - B
* =f A B
** returns true of the two are equal
* !=f A B
** returns true if the two aren't equal
* <nowiki><f</nowiki> A B
** returns true if A is less-than B
* <nowiki>>f</nowiki> A B
** returns true if A is greater-than B
* <nowiki><=f</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=f</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* divf A B
** returns the value of A divided by B
* modf A B
** returns the modulus of the two arguments
* minf
** returns the lowest valued argument of all provided arguments
* maxf
** returns the highest valued argument of all provided arguments

===Strings===

* =s A B
** returns 1 if the string matches, 0 otherwise
* !=s A B
** returns 0 if the string matches, 1 otherwise
* <nowiki><s</nowiki> A B
** returns true if the C strcmp returns less-than 0
* <nowiki>>s</nowiki> A B
** returns true if the C strcmp returns greater-than 0
* <nowiki><=s</nowiki> A B
** returns true if the C strcmp returns less-than-or-equal-to 0
* <nowiki>>=s</nowiki> A B
** returns true if the C strcmp returns greater-than-or-equal-to 0
* strcmp A B
** returns 1 if the string matches, 0 otherwise (unlike the C version with returns the disparity)
* strstr H N
** returns the position of N in H - otherwise -1 is returned
* strlen S
** returns the length of the string
* strreplace S O N
** replaces all instances of O inside string S with N

==String/text formatting==

These commands are used to format aliases which are normally huge bits of text

* concat C
** everything you type after will be returned; with expressions and substitutions performed
* concatword C
** the next 25 arguments will be executed and subsequently concatenated without any spaces between them
* format F S1 S2 S3 S4 S5 S6 S7 S8 S9
** F is a string containing %# tokens, format substitutes the arguments with their respective %# tokens (ie: S5 will replace %5)

=See Also=

*[[map_config|Map Configuration]]

RPG cutscene

2012-07-03T05:25:54Z

Hirato:

'''This doucmentation is outdated and does not apply to the current version of sandbox!!!'''

=Intro=

Cutscenes are defined much like everything else, and generally also during the configuration phase. Cutscenes consist of multiple directives which may or may not be nested. All the directives can create additional ones. Note that the cutscenes only allow control of the camera, entities and creates are to be moved via script. See the scripting page.

The following command is used to create a new one... 
r_new_cutscene ACTIONS POST 
the POST argument is generally used to set variables (ie, don't play this cutscene again), and prepare the map should the player choose to skip it.

an example of a simple cutscene is as follows

<code>
r_new_cutscene [
r_cutscene_viewspin 180 0 0 5000
] [
echo "cutscene done playing"
]
</code>

To start a cutscene, you must invoke: r_start_cutscene INDEX; To start the above, you'd use

<code>
r_start_cutscene 0
</code>

=General Directives=
==Action/Delay==
Introduce a delay in a cutscene before performing an action:

<code>
r_cutscene_delay DELAY ACTION
</code>

* DELAY: delay in milliseconds before to perform action
* ACTION: action block

Many cutscenes command have DELAY and ACTION as their two last parameters, which allows to chain to the next action after the delay has expired.

==Cond==

==Iterate/Loop==

==Signal==

==Subtitle==
Displays a subtitle with the given color.

<code>
r_cutscene_subtitle TEXT R G B DELAY ACTION
</code>

* TEXT: text to display
* R, G, B: red, green and blue values for the text color
* DELAY: delay during which the text remains displayed
* ACTION: action to perform after the delay

=Camera movement=
==Move camera==
Move the camera to the position of a given camera tag:
<code>
r_cutscene_movecamera TAG DELAY ACTION
</code>
or
<code>
r_cutscene_moveaccelcamera TAG DELAY ACTION
</code>

* TAG: camera tag
* DELAY: delay during which the camera will move to the target (use 0 for immediate)
* ACTION: action to perform after the delay

The first command will move the camera in a linear way to reach the target camera tag. The second one will do the same in an accelerated way.

==Move camera to a specific position==
Move the camera to a specific position:
<code>
r_cutscene_movespecific X Y Z DELAY ACTION
</code>
or
<code>
r_cutscene_moveaccelspecific X Y Z DELAY ACTION
</code>

* X, Y, Z: absolute coordinates to where the camera must move
* DELAY: delay during which the camera will move to the target (use 0 for immediate)
* ACTION: action to perform after the delay

The first command will move the camera in a linear way to reach the given position.
The second will do the same in an accelerated way.

==Change Camera View Angle==
Change the camera's view angle to match a camera tag's view angle.
<code>
r_cutscene_viewcamera TAG DELAY ACTION
</code>
or
<code>
r_cutscene_viewaccelcamera TAG DELAY ACTION
</code>

* TAG: camera tag from which to use the view angle
* DELAY: delay during which the camera's angle will be modified
* ACTION: action to perform after the delay

The first command will change the camera's view angle in a linear way to reach the target angle.
The second command will do the same in an accelerated way.

==Change Camera View Angle using specific values==
Change the camera's view angle to match the given angle values.
<code>
r_cutscene_viewspecific YAW PITCH ROLL DELAY ACTION
</code>
or
<code>
r_cutscene_viewaccelspecific YAW PITCH ROLL DELAY ACTION
</code>

* YAW, PITCH, ROLL: target angle
* DELAY: delay during which the camera's angle will be modified
* ACTION: action to perform after the delay

The first command will change the camera's view angle in a linear way to reach the target angle.
The second command will do the same in an accelerated way.

==Viewspin==
Spins the current view using the given relative angle movements.

<code>
r_cutscene_viewspin YAW PITCH ROLL DELAY ACTION
</code>

* YAW, PITCH, ROLL: relative angle direction in which to spin the current view's angle
* DELAY: duration of the movement
* ACTION: action to perform after the delay

=Other directives=
==Sound==

==Soundfile==

==Overlay==

==Solid==

==Viewport==

==Focus==

RPG tutorial

2012-06-01T07:32:54Z

Hirato: /* 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=

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
<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=

<Broken Link Removed>

RPG todo

2012-05-31T11:56:21Z

Hirato: updates!

=Gameplay=
* hotkeys
* special item properties
** money (constant value for all purposes)
** cursed status
** unidentified status
*** hide true power or make it a lot less useful?
* (maybe?) character generation
* sneaking/stealth
** light and visibility
** silhouettes and light levels?
** stealing
* proper friendly fire protection
** 0 - no protection (default)
** 1 - prevents you from hurting yourself
** 2 - 1 + prevents you from hurting allies
** 3 - allows injury to hostile characters only
* spell types
** movement (paralysis counters)
** vocal (silence counters)

=Logic=
* the consume use case for books and potions.
* statusgroups on items
** temporary spells that alters the properties of the weapon
** multiple at once with different targets.
* temporary spell effects for wielded items,
** multiple status effects on a single use, separate chargeflags, multiplier, duration and element.
** make sure to use each for the right purpose
* Projectiles
** improve ricochet, gravity related stuff is funky
* status types
** dispel - should work on individual effects
** silence
** paralysis/stun
* Expose a tonne of constants to Cubescript for configuration at the game maker's discretion. These include leveling and power curves
* arbitrary trigger bounding box scales

=GUI=
* inventory
** item examination
* status effects
* trade
* stats
* crafting
* journal
* newui variants

=Recipes=
* (maybe) allow in game apparatuses to act as a catalyst
** (maybe) several catalysts and ingredients list? or just duplicate and alter the recipe?

=AI=
* queued prioritised actions
** most important done first
** multitasking
* waypoints
** randomness
** state - don't favour waypoints which are in use
* ai tags
** identify purpose and effect of entities in game world for the AI (parsing the script for these is simply not practical)
*** alternatively use simpler more specific types, such as "door", "container", "portal" and "mover" as opposed to a singular "object"

=Cutscenes=
* some sort of skipping bar (1000 ms?) to prevent accidental skips

=Renderer=
* particles for active spell effects
* render attachments/equipment
* animations for weapons
** generic animations, unarmed strike, melee strike, bow shoot, gun shoot, etc

=Journal=
* sorting and filters

=Sound=
* sounds while charging spells
* sounds for projectile firing, travel and death
* sounds for active statusgroups
* (maybe) voiced dialogue

=I/O=
* flat file export of current script/data definitions (maybe)
** couple with ingame menus for realtime modification (maybe)
* save and restore AI directives

=Particles=
* set particle effects for entity afflicted status effects
* vary spawned amount of particles depending on distance (few when close, full amount when far away)

RPG editing

2012-05-31T11:53:37Z

Hirato: emphasis!

= Adding spawn points =

There are two types of spawn points you can add to the world. The first is the generic kind any entity can spawn at when directed to do so through script. The second is the dedicated kind. Dedicated spawn points are named after the type of entity they will create and will display a preview of the entity in question. The entity is always spawned there when the map is initialised.

We strongly recommend that you save your game and map before you mess with any freshly spawned entities, '''ESPECIALLY''' if they're designed to transfer you to another map.

For example, if we wanted to spawn container #3, we might use the following
<code>
newent container 3
</code>

= Game state =

All simulation (apart from the player's movement) is paused during editmode and neither entities or particles are rendered by default. By default the map is also reset when you exit edit mode, sending the "load" signal to the map and respawning everything at the dedicated spawn points.

There are two variables that can be used to tweak this behaviour.
<code>
edittogglereset 0 // turns off the reset after exiting editmode
editdrawgame 1 // draws entities and particles in editmode
</code>

= Entity Previews =

Dedicated spawn points will draw a transparent version of the entity's model by default. If you don't like this or are having graphical issues, you can tweak this through the provided variable.

<code>
entpreviewalpha .4 // 0 = off, 1 == no transparency
</code>

= Reloading definitions =

As of 2.7.0, the RPG has gained a command which will reload all definitions.

Before you execute it, you should take care to '''save your map and game''' in case there are any critical errors in the definitions. If there are the RPG will respond in much the same way as it would when you try to start or load such a game, '''it will abort and return to the main menu.'''

Once you're prepared, the following command will reload the definitions. You may need to toggle editmode for some of them to take effect.
<code>
r_rehash // reloads all game definitions
</code>

= Modifying definitions ingame =

For testing purposes, you can select "Browse Definitions" in the menu whilst inside editmode to alter most properties of existing definitions. '''None of these changes are permanent''' unless done outside of the game.

RPG

2012-05-31T11:51:28Z

Hirato: /* Definitions */

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_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.

Platinum Arts Sandbox Free 3D Game Maker:Community Portal

2011-12-22T06:12:55Z

Hirato: Reverted edits by Zilking75 (Talk) to last revision by Hirato

Possible upcoming events. Please contact us if you are interested!

* Kid friendly RPG
* Water Waters - DM type game with water guns and water balloon bazookas!
* Kart mode into an actual racing game.
Also Sandbox is being used in more and more schools! The goal is to try to get Sandbox into as many schools as we can, and the more schools and kids using it the better! Any help that you can give us is much appreciated!

Cooperative Editing 2

2011-12-22T06:12:11Z

Hirato: Undo revision 1575 by RenéFriedman (Talk)

OK so you can't port-forward, Then this tutorial is for you.
First make sure you have Hamachi ( http://hamachi.en.softonic.com/ ), It is free.

Ok first run the program after you install.

Then you go to network and name a ID and pass.

Then u tell the person you want to Co-op with, to get Hamachi.

Then tell him to join your network on hamachi with same id and pass as you used.

Now the person who is going to host it has to run server.bat and give your friend the IP that's under your name name in big letters.

Now go into sandbox and type in /connect IP
and your friend has to also do the same thing.

COOP Commands
/map "allows you to vote on a map"
T Button allow's you to talk!

Platinum Arts Sandbox

2011-12-22T06:12:03Z

Hirato: Undo revision 1574 by RenéFriedman (Talk)

About Platinum Arts Sandbox Free 3D Game Maker:

Platinum Arts Sandbox Free 3D Game Maker is an open source game design program for kids and adults. Through the ingame and cooperative editing and focus on ease of use the program is easy enough for kids to use but powerful enough for full game projects. Sandbox includes Save The Princess Gameplay, an RPG Maker, a Sidescoller maker, a Movie Maker aka Machinima, Save The Banana Base Capture, and more! Sandbox is already being used in many schools and colleges throughout the world and included in game design contests.

Platinum Arts Sandbox will be easy enough for kids to use but also powerful enough for full game projects.

Contributing

2011-12-13T05:45:36Z

Hirato: /* Style */

=Code=

examples of code contributions
* bug fixes
* additional features
* cleanups

if you've any of the above, send them to Hirato, the code will be included if he approves. He can be contacted through the [http://forum.sandboxgamemaker.com forums] (the PM system) or via [irc://irc.oftc.net/sandbox IRC] (the latter is recommended). 
If you desire any feedback on your code, post it in the "Show of Your Work in Progress" forum, and tag it with [patch] - eg "[patch]continuous jumping", for a patch that makes you jump nonstop.

If you lack any ideas of what to implement, should you wish to contribute in this way, there are various todo lists that should help you out
* http://www.svn.kids.platinumarts.net/32pas32/trunk/sandboxtodo.txt
* http://www.svn.kids.platinumarts.net/32pas32/trunk/src/rpggame/rpgtodo.txt
* http://www.svn.kids.platinumarts.net/32pas32/trunk/src/sspgame/ssptodo.txt

Making several good patches, which are accepted, is a good way of convincing us you have what it takes to be on the development team.

==Style==
The files in the engine and the respective game modules use slightly differing styles... The easiest way is simply to remain consistent with the style present in the file.

For more detailed information, see [[Coding Style]]

==licensing==

By sending in your code, YOU give US permission to relicense the code under the zlib/libpng license and include it as part of our source distribution(s), irregardless of the code's original license. By extension, this means you're NOT PERMITTED to REVOKE permission for us to use the code, should you decide you no longer wish for your code to be inside sandbox

=Art=

This category includes custom maps, models and textures. Just send them in, if they're of acceptable quality, and of an acceptable license, we'll add them right in. 
You can also post them on the forums, we tend to look there occasionally, and the community would doubtlessly be excited to see what people are making/working on for sandbox

==licenses==

These are a listing of licenses we recommend for art assets included in sandbox.

* Creative Commons - Attribution
* Creative Commons - Attribution + Share-Alike
* MIT/X11
* Public Domain

=Other=

==Testing==

As a rule of thumb, there are '''ALWAYS''' bugs, if you're up to it, just use sandbox as you normally would, and keep an eye out for any oddities, and put extra effort into trying to break things. Should something go wrong, give us the exact steps you took, and we'll do out best to fix it. We recommend using the [[Development|SVN version]].

See Also
* [[Development]]
* [[Bug reports]]

Coding Style

2011-12-13T05:40:06Z

Hirato: Created page with '= Patches = Patches should be sent using the unified style. These can typically generated through '''diff -u''', svn diff uses this format by default. These patches contain some …'

= Patches =
Patches should be sent using the unified style. These can typically generated through '''diff -u''', svn diff uses this format by default. These patches contain some context information which makes them much easier to apply should there be intermediary changes and generally they are human readable.

= Source Code =

These are just rough guidelines, when it doubt mimic the style of the surrounding code.

When not writing one liners, braces should be placed on their own lines with the programming statements following on a new line. Braces are to maintain the current level of indentation. Should you write a if, else or while statement that only does one thing, braces are optional.

Good
<code>
int myfunc() { return 4; }

if(conditon) { function(); variable++; }
else { function2(); var2++; }

int myfunc()
{
return 4;
}

if(condition)
{
function();
variable++;
}
else
{
function();
variable++;
}
</code>

Bad
<code>
int myfunc() {
return 4
}

int myfunc()
{ int a = 4;
return a;
}

int myfunc()
{
return 4
}

int myfunc()
{
if (cond)
{
return 4;
}
else
{
return 2;
}
}

if(condition) {
stuff()
} else {
dostuff();
}
</code>

Indentation wise, you will be using either 4 spaces or tabulators. Which depends on the file you modify so keep an eye out. As a general rule the engine stuff and the FPS game uses 4 spaces whilst everything else uses tabs. Tab size should be irrelevant but the best experience should be with a size of 4.

There aren't many fixed rules and you are allowed some freedom provided they make things more readable, with that said you are encouraged to indent liberally rather than conservatively.

Good
<code>
switch(var)
{
case 1:
#ifdef A
break;
#endif
case 2:
case 3:
default:
break;
}

class A
{
public:
void stuff() {}
}
</code>

Discouraged
<code>
{
switch(var)
{
case 1:
#ifdef A
break;
#endif
case 2:
case 3:
default:
break;
}
}

class A
{
public:
void stuff() {}
}
</code>

Subjective
<code>
glBegin(GL_TRIANGLE_STRIP);
glVertex2i(sx, sy);
glVertex2i(ex, sy);
glVertex2i(sx, ey);
glVertex2i(ex, ey);
glEnd();
</code>

When defining prototypes and variable names, place any special qualifiers (such as * or &) next to the variable name as opposed to the type. This is done mainly due to C/C++ parsing rules and the interest of readability. This also goes for prototypes and their argument lists.

Good
<code>
const char *A, *B;
const char *strstr(const char *haystack, const char *needle);
</code>

Bad
<code>
const char* A, B; //note the types are const char*, and const char respectively
const char* strstr(const char* haystack, const char* needle);
</code>

Variable and function names should be short, succinct and to the point. We should be able to infer from the name alone what the variable's purpose is. Where possible, use common, accepted names for variables and descriptive verbs for functions. For example i, j, k or n are excellent variable names when you're counting or checking against some sort of index, and verbs like "destroy" are ideal for functions that are intended to remove something from the game. When it comes to writing the names, the rules as as follows

* Hungarian notation is not allowed, use '''int num''' over '''int iNum'''
* CamelCase is discouraged, but is accepted. Note that ThisIsPreferred and that thisIsNotPreferred.
* constants should always be written in ALL CAPS. macros are also preferred this way but this is not a strict requirement

Good
<code>
int i, j, count;

enum
{
FIRST = 0,
SECOND,
THIRD
};
</code>

Bad
<code>
int iCount;
bool bMerge;

enum
{
First = 0,
Second,
Third
};
</code>

When defining prototypes, especially when doing it as an extern or the like, name all the arguments. C/C++ does allow you to only specify the types, but we will not permit such code. You are welcome to specify defaults where they make sense.

Good
<code>
void function(int a, int b, float &ref, const char *ptr = NULL);
</code>

A crime against humanity
<code>
void function(int, int, float&, const char*);
</code>

Comment wise, we believe in writing clean, simple, self documenting code. This obviously isn't always possible and there may be strange quirks, odd preconditions or convoluted logic and it is these cases you must comment. As a rule of thumb if you write something and there's a chance that you or someone else might trip up if you make further modifications try to use it or simply understand it, make a comment.

= Cubescript =

Main Page

2011-12-13T03:45:54Z

Hirato: /* Development */

'''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]]
*[[Kid Matthew's RPG Tutorials]]

Cubescript

2011-12-04T12:41:00Z

Hirato: /* substitution */

Cubescript is the scripting language utilised within the sauerbraten/cube2 engine. it is used to set aliases, variables, create binds and generate the menu.

=Writing in Cubescript=

==Aliases==

The brunt of cubescript is concerned with Aliases. Aliases have 3 basic uses.
* store lists and values for extended periods of time
* store temporary lists and values
* grouping a set of commands which are useful when combined

There are two ways to declare an alias. You can do it via infix notation, or by using the alias command. It should be noted that aliases are the exception to the rule, infix notation is only available for creating aliases.

A VERY important note, alias specific operations are available to aliases only. this means builtin variables can't be set or overridden through alias, =, pop and push (among others).

<code>
//command
alias myalias [1]

//infix variant
myalias = [1]
</code>

===executing aliases===

To execute an alias, you execute it like any other command. if I had an alias named '''myalias''', I would simply invoke ''''/myalias''' to execute it.

These aliases also have access to a class of special aliases. Those are the temporaries in which arguments are stored. There's also a useful variable named 'numargs' which tell you how many arguments were provided. The aliases containing the arguments are named arg. they are numbered and enumerated, starting from 1, so you'd use $arg1 to access the first argument. This does not start at 0, since arg0 is the command's name (arg0 is also not defined.. ever, nor included in numargs).

<code>
//prints all arguments to screen, one by one
//see the other comments for an explanation

print = [ //declares an alias named print
loop i $numargs [ //loops $numargs times, setting i to the current iteration
echo (getalias (concatword arg (+ $i 1)) //gets the value of the arguments, by accessing $arg1 $arg2 $arg3....
] //close loop
] //close print alias
print I like unicorns //should print I like unicorns on 3 separate lines
</code>

===push and pop===

Push and pop used to be two separate instructions, but since the advent of the new Cubescrpt interpreter/compiler (2.6.1), they have been merged into a single instruction. The syntax for this singular stack manipulation command is as follows.

push variable value body

The stack is automatically popped after execution

<code>
myalias = "candy"
push myalias "lollipops" [
echo $myalias
]
echo $myalias

//expected output
//lollipops
//candy
</code>

==Syntax==

Cubescript is not your typical scripting language. Cubescript is not the most flexible, or the best language, but it more than adequate for our needs and purposes. Cubescript draws its main inspiration from quakescript and from Lisp. It is therefor said that Cubescript contains many "Lispisms". Below is a summary of notable features/quirks.

* comments are denoted by //
* both newlines and ; denote the end of a call.
* newlines will automatically close of any strings you may have forgotten to. (you should not rely on this)
* substitutions are done through the use of $ and @ tokens, (See below)
* everything is a function which may take arguments. With the exception of setting an alias, infix notation does not exist
* there are no arrays or vectors, only lists.
* most implementations have a 25 word limit. This means commands can be invoked with up to 24 arguments

one liner example

<code>
alias hi [say "hi"; sleep 5000 [say "Hi again"]]
</code>

multi liner example

<code>
alias hi [
say "hi"
sleep 5000 [
say "Hi again"
]
]
</code>

it's obvious what the above code does, it'll make your character say hi, and wait 5 seconds before saying hi again.

indenting is done in levels, the Tabulator (TAB) key is usually used to indent the text. while not necessary, it tends to make it bigger, and more legible as seen in the above example (when you get to big stuff, you'll thank yourself for indenting it.

As a rule of thumb, pretty much only [ increases the indentation level. Also note, ", ] and ) can close each other, so make sure you close them off properly

==containers==

Containers in cubescript are of 3 specific types, "", () and [] - all of these have significant differences in operation and use

==="" container===

"" containers are used to store things EXACTLY as they are written, with a few small exceptions - in-text commands which are denoted by a preceding ^. They are as follows

* ^f#
** ^f# is used to colour text. # must be replaced by either a number or a capital letter (A-Z). r and s are special control characters which will restore and save the text's current colour respectively.
* ^n
** insert a '\n' character (newline/linefeed)
* ^t
** inserts a '\t' character (tabulator)
* ^"
** inserts a quote (")

===() container===

() containers are used mainly for logic/arithmetic operations. They are usually nested inside [] blocks, and unless they are nested inside []'s they're permanently substituted with their results.

For example - the following will turn into an infinite loop. The condition is initially evaluated and substituted with one and since 1 can never = 0, it's true forever more

<code>
i = 0
while (= $i 0) [i = (+ $i 1)]
</code>

the following code on the otherhand is devoid of such issues. Being nested inside the [] means it's not substituted and evaluated each cycle

<code>
i = 0
while [= $i 0] [i = (+ $i 1)]
</code>

===[] container===

This container is used for nesting, deferring execution of it's contents, deferring calculations and substitutions of () containers, and substitutions of aliases/variables written with a @ prefix (note several levels are needed to achieve this). [] containers are also the ONLY container capable of spanning multiple lines.

This is the most used container and due to it's properties, is ideal for creating aliases.

generally statements in cubescript can't span multiple lines. If you should use this container and occupy several, the execution of the prior command continues exactly where this container finished off. This can be demonstrated with an if statement.

<code>
if 1 [
do
stuff
] [
do
other
stuff
]
</code>

==substitution==

there are two principle ways of substituting values in cubescript, the first is through the use of $ tokens, the second is through the use of @ tokens.

a very simple example:
<code>
myalias = 5
echo $myalias
</code>
myalias is substituted into the echo statement, so you should see 5 printed to the top-left of the screen

using the @ token would have also resulted in the same behaviour
<code>
myalias = 5
echo @myalias
</code>

There's a big difference between the two, the @ token can be used to concatenate stuff together, $ can't. @ is also substituted immediately up to the first level of nesting. (this can be incremented by using additional @ tokens, ie @@ for 2 levels of nesting). Do take note that too few @ tokens may cause a substitution to happen too late, and too many may likewise cause it to happen too early or cause other weird and subtle issues.

'''An example of use in a level 1 nest'''

<code>
myalias = "I am awesome"
mymenu = [guitext @myalias]
</code>
if you were to type /echo $mymenu, it should read: guitext "I am awesome"; using the $ token on the other hand

<code>
myalias = "I am awesome"
mymenu = [guitext $myalias]
</code>
typing /echo $mymenu should produce: guitext $myalias

'''An example of concatenation'''

as i mentioned, @ also allows you to concatenate stuff together, which could result in shorter and simpler scripts. It should be noted that this can also result in extreme obfuscation
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [ do [
echo $myalias@i
]]
</code>
this should print 5, 3.1415 and 2.481 respectively

the purely $ token equivalent
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [
echo (getalias (concatword myalias $i))
]
</code>

'''Lookup of a Lookup'''

There are two ways to look up multiple things; the first is by encasing it inside 'getalias', the second involves using multiple lookup tokens. There is a caveat with the second method, while it works on more types, it's only available in sandbox as of 2.6.1.

All 3 of the below examples should print "victory!"
<code>
alias1 = "alias2"
alias2 = "alias3"
alias3 = "victory!"

//the first method
echo (getalias (getalias $alias1))

//the second method; 2.6.1
echo $$$alias1

//to show compatibility with @
do [
echo $$@alias1
]
</code>

==Branching/Decisions==

Decisions are based on 6 key commands, '''if''', '''?''', '''cond''', '''case''' (integer), '''casef''' (float) and '''cases''' (string). There are also other ways to do this. For example you might be able to easily query something about an object, where it's obviously unique. You would then execute an alias whose name has this unique bit attached onto the end. This is an advanced method and is generally not recommended.

===if and ?===

Arguments: Cond True False

Unlike most other languages, cubescript's '''if''' contains an implicit else, in short we do not have an else statement. The provided condition is true if it ends up as a series of alpha numerics, or in the case of a number, as a value other than 0.

<code>
myalias1 = 5
myalias2 = "woot"

//if else-if else
if $myalias1 [
echo "myalias1 is true"
] [
//this shows the alpha numerics case
if $myalias2 [
echo "myalias1 is false and myalias2 is true"
] [
echo "myalias1 is false and myalias2 is false"
]
]
</code>

'''?''' acts exactly the same way, but there's one HUGE difference. '''?''' does not execute the chosen result.

<code>
//an example of where ? can be used where if would fail
items = 1
echo (format "You are carrying %1 item%2." $items (? (= $items 1) "" "s"))
</code>

===cond===

basically you provided a several pairs of arguments, the first half of the pair is the condition, and the second is the result. To put it in a programming perspective, this is like creating a long line of if else's together. Execution stops when the first condition is matched. Should you place several conditions where more than one may be true at any one time, only the first will be executed.

The following example assumes you have a light entity selected

<code>
lightstrength = [
cond [< (ea 0) 0] [
echo "It's like a black hole!"
] [= (ea 0) 0] [
echo "Blindlier than science!"
] [< (ea 0) 8] [
echo "It's weaker than Billy's night light!"
] [< (ea 0) 32] [
echo "Nice night light you got there"
] [< (ea 0) 96] [
echo "It's like a lamp, but it's not a lamp"
] [< (ea 0) 512] [
echo "By Jove! I can actually see the ground!"
] [>= (ea 0) 512] [
echo "Dark places are icky, don't you agree?"
]
]
</code>

===case===

This works similar to switches in most programming languages. The biggest difference is that you can't break out, nor evaluate multiple cases (aka, fallthroughs).

The first argument tells it which variable to use. The following arguments are given in pairs, the first half is the state, the second is the result.
If the state is a null type, it is considered the default case. The easiest way to generate a null type is to use ()

The following example requires a particles entity to be selected, it will print out what type it is. Do note that this example exceeds the 25 word limit.

<code>
parttype = [
pname = ""

case (ea 0) 0 [
pname = "Fire and Smoke"
] 1 [
pname = "Fire"
] 2 [
pname = "Smoke Plume"
] 3 [
pname = "Smoke"
] 4 [
pname = "Fountain"
] 5 [
pname = "Explosion"
] 6 [
pname = "Meter"
] 7 [
pname = "Vs Meter"
] 8 [
pname = "Text"
] 9 [
pname = "Flare"
] 10 [
pname = "Lightning"
] 11 [
pname = "Fire"
] 12 [
pname = "Smoke"
] 13 [
pname = "Water"
] 14 [
pname = "Snow"
] 15 [
pname = "Leaves"
] 32 [
pname = "Lens Flare"
] 33 [
pname = "Fixed Size Lens Flare"
] 34 [
pname = "Sparkly Lens Flare"
] 35 [
pname = "Sparkly Fixed Size Lens Flare"
] () [ //default
pname = "A very pretty albeit unsupported particle"
]

echo The particle you have selected is of type: $pname
]
</code>

===Naming===

another way of doing decisions/branches is to use paths with different names. This has limited usage though. in short it requires you to query some information to concatenate onto another word, which you would then execute. There are exceptions. Other than the number of results you can query, there is no limit here. A handy trick is to have several results execute the same alias, though this requires that they differ only slightly at most in operation.

<code>
//This example demonstrates the exception
//it requires you to have an entity selected
//This will conflict with showquickgui
newgui "particles" [guitext "It's like a random series of nothing"]
newgui "light" [guitext "SHINY!!!!"]
newgui "jumppad" [guitext "boing!"]

identify = [showgui (et)]
</code>

<code>
//shows a more standard example, at present this is exclusively used by edithud (see stdedit.cfg)
//this also requires you to have an entity selected.
identlight = [echo "it's so bright..."]
identdynlight = [identlight] // to demonstrate how different results can execute the same script
identjumppad = [echo "boing? boing!"]
identparticles = [echo "Please don't change it to a lens flare!"]

identify = [ if (enthavesel) [ident@(et)] [echo Select an entity first!]]
</code>

==Lists==

Ordered lists are the closest cubescript has to the likes of arrays. Their declaration is identical to any alias, as they are simply items in a string separated by white space. Using [] is recommended as the container of choice, since it allows you to use "" to include multi-word items in a list as a single unit as well as define the list over multiple lines. "" can also be used to define lists. An example can be inspected below.

<code>
//declares 2 equivalent lists of 3 elements
mylist1 = [one two "three four"]
mylist2 = "one two ^"three four^""

//prints the 3rd element
echo (at $mylist 2)
</code>

'''loops'''

There are at least 2 ways to loop through a list. The first method involves the use of looplist to iterate over it and the second the use of listlen to determine the list's length. The difference between using looplist and listlen is that you will not have a reliable way of determining an element's index and won't have to manually fetch the element from the list. Basically looplist is faster at the cost of some information and should be used in all cases where the index does not need to be known.
An example can be inspected below.

<code>
mylist = [
0
1
3.14159265359
2.71828182845
sqrt(-1)
1 //to demonstrate that the index cannot be determined reliably with looplist
]

//demonstrates looplist
looplist var $mylist [
echo number (listfind item $mylist [strcmp $var $item]) : $var
]

//demonstrates a loop + listlen combo
loop i (listlen $mylist) [
echo number $i : (at $mylist $i)
]
</code>

'''concatenation'''

Concatenation is pretty simple, albeit not very efficient. It is basically, setting the list to itself plus the additional item. This is of course best achieved through the concat commands.

<code>
mylist = [1 2 3 4 5 6 7 8 9 10]

//using concatword
mylist = (concatword $mylist " " 11)

//using format
mylist = (format "%1 %2" $mylist 12)

//using concat - we're also preparing it for pretty list
mylist = (concat $mylist 14)

//pretty list does add an item onto the list, but it changes the format dramatically and the new item is placed before the end
//it is ideal more so for making things pretty for presentation than concatenation
mylist = (prettylist $mylist 13)

//should print 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 14
echo mylist is $mylist
</code>

concat returns everything given to it as a singular item, spaces and all. Concatword ignores spaces and ""'s must be explicitly provided. Concat is therefor ideal to add lists together.

<code>
mylist1 = [1 2 3 4 5]
mylist2 = [6 7 8 9 10]
mylist3 = [11 12 13 14 15]
mylist4 = [16 17 18 19 20]
mylist5 = [21 22 23 24 25]
mylist6 = [26 27 28 29 30]
finallist = ""

//how concatword merged three lists
finallist = (concatword $mylist1 " " $mylist2 " " $mylist3)

//concat unlike the above does not require
finallist = (concat $finallist $mylist4 $mylist5 $mylist6)

echo (prettylist $finallist)
</code>

'''finding'''

there are two ways to find things, the first is to use listfind, and the second is to loop through the list. Both are demonstrated in the example below

<code>
mylist = [
"Jack"
"Jane"
"Joseph"
]

//This is an example of looking for a single element, note that this variant of...
//strcmp unlike its C counterpart returns 1 when strings are equal
//in this example, a 0 should be printed at the top of your screen - listfind returns the index
echo (listfind f $mylist [strcmp $f "Jack"])

//In this example, -1, as Jill is not in the list
echo (listfind f $mylist [strcmp $f "Jill"])

//in this example, we want to find anything which contains an e and add it into a list
results = ""
looplist var $mylist [
if (>= (strstr $var "e") 0) [
results = (concatword $results "^"" $var " ^"")
]
]

//this should print: Jane Joseph
echo $results
</code>

=List of commands=

==General==

The following commands are quite often used in a lot of scripts.

* alias N B
** creates an alias named N with body B, the intext version is denoted as N = B (equivalent to alias N B)
* at S I
** returns the Ith element in string S, note that counting starts from 0. If it's out of range, "" is returned
* getalias A
** returns the value of A. this also does not produce a warning should an alias be undeclared, nor complains when fetching built in variables.
* if C T F (F is optional)
** if condition C is true, execute T, otherwise F is executed
* listlen S
** returns the amount of elements in list S
* loop V N B
** loops N times, and aliases the current iteration to V; B is executed every iteration.
* result S
** returns the string, useful when aliases need to be executed
* rnd N L
** chooses a random number between 0 and N-1 (inclusive). L sets the lower limit. eg rnd 12 7 will return either 7 8 9 10 or 11
* sleep N B
** executes B after a delay of N milliseconds. NOTE: even if N is <= 0, it'll still wait till the next frame before executing it
* while C B
** executed B while C is true. NOTE: surround C in a [] container, or you risk an infinite loop due to the condition not being reevaluated.

==Map Configuration==
'''''ONLY APPLIES TO FPSGAME'''''

The following commands are useful in level only aliases

*triggerstate
*level_trigger
**level trigger is invoked as level_trigger_1 = [] as an example, the end number is the 4th number in the mapmodel's strings
*level_base
**Used to give bases names in capture mode. This is unfortunately unused in PAS

==Binds==

The following commands are useful in binds.

*onrelease

==Gui Creation==

For newui, please see [[new menu editing]]

These commands are used to create various menus.

* cleargui
* guibar
* guibutton
* guicheckbox
* guifield
* guikeyfield
* guiimage
* guilist
* guirolloveraction
* guirollovername
* guislider
* guilistslider
* guinameslider
* guistayopen
* guitab
* guitext
* guititle
* guistrut
* newgui

==Comparisons==

The functions here can change the values, or return a logical comparison
for all intents and purposes, the C version of booleans apply here; values not equal to 0 are true - and functions that return true return 1

===Integer Arithmetic===

* + A B
** returns the value of the numbers added together
* <nowiki>*</nowiki> A B
** returns the result of multiplying A and B
* - A B
** returns the value of A - B
* = A B
** returns true of the two are equal
* != A B
** returns true if the two aren't equal
* <nowiki><</nowiki> A B
** returns true if A is less-than B
* <nowiki>></nowiki> A B
** returns true if A is greater-than B
* <nowiki><=</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* ! A
** if the argument is false, it returns true
* &&
** returns true if all arguments are true
* ||
** returns true it at least one argument is true
* div A B
** returns the value of A divided by B
* mod A B
** returns the modulus of the two arguments
* min
** returns the lowest valued argument of all provided arguments
* max
** returns the highest valued argument of all provided arguments

===Bitwise Integer Operations===

* ^ A B
** returns the value of A xor B ie (^ 8 4) is 12 - (^ 12 4) is 8
* & A B
** returns the value of the bits both A and B have
* | A B
** returns the value of the bits either A or B have
* ~ A
** returns the inverted bitwise version of A ie (& (~ 128) 255) is 127
* ^~ A B
** xor;s the arguments after applying an inversion on B
* &~ A B
** and's the arguments after applying an inversion on B
* |~ A B
** or's the arguments after applying an inversion on B
* <nowiki><<</nowiki> A N
** shifts A N bits
* <nowiki>>></nowiki> A N
** shifts A -N bits

===Floating Point Arithmetic===

Generally these just have an -f suffix

* +f A B
** returns the value of the numbers added together
* <nowiki>*f</nowiki> A B
** returns the result of multiplying A and B
* -f A B
** returns the value of A - B
* =f A B
** returns true of the two are equal
* !=f A B
** returns true if the two aren't equal
* <nowiki><f</nowiki> A B
** returns true if A is less-than B
* <nowiki>>f</nowiki> A B
** returns true if A is greater-than B
* <nowiki><=f</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=f</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* divf A B
** returns the value of A divided by B
* modf A B
** returns the modulus of the two arguments
* minf
** returns the lowest valued argument of all provided arguments
* maxf
** returns the highest valued argument of all provided arguments

===Strings===

* =s A B
** returns 1 if the string matches, 0 otherwise
* !=s A B
** returns 0 if the string matches, 1 otherwise
* <nowiki><s</nowiki> A B
** returns true if the C strcmp returns less-than 0
* <nowiki>>s</nowiki> A B
** returns true if the C strcmp returns greater-than 0
* <nowiki><=s</nowiki> A B
** returns true if the C strcmp returns less-than-or-equal-to 0
* <nowiki>>=s</nowiki> A B
** returns true if the C strcmp returns greater-than-or-equal-to 0
* strcmp A B
** returns 1 if the string matches, 0 otherwise (unlike the C version with returns the disparity)
* strstr H N
** returns the position of N in H - otherwise -1 is returned
* strlen S
** returns the length of the string
* strreplace S O N
** replaces all instances of O inside string S with N

==String/text formatting==

These commands are used to format aliases which are normally huge bits of text

* concat C
** everything you type after will be returned; with expressions and substitutions performed
* concatword C
** the next 25 arguments will be executed and subsequently concatenated without any spaces between them
* format F S1 S2 S3 S4 S5 S6 S7 S8 S9
** F is a string containing %# tokens, format substitutes the arguments with their respective %# tokens (ie: S5 will replace %5)

=See Also=

*[[map_config|Map Configuration]]

Cubescript

2011-12-04T12:39:39Z

Hirato: /* substitution */ fix example

Cubescript is the scripting language utilised within the sauerbraten/cube2 engine. it is used to set aliases, variables, create binds and generate the menu.

=Writing in Cubescript=

==Aliases==

The brunt of cubescript is concerned with Aliases. Aliases have 3 basic uses.
* store lists and values for extended periods of time
* store temporary lists and values
* grouping a set of commands which are useful when combined

There are two ways to declare an alias. You can do it via infix notation, or by using the alias command. It should be noted that aliases are the exception to the rule, infix notation is only available for creating aliases.

A VERY important note, alias specific operations are available to aliases only. this means builtin variables can't be set or overridden through alias, =, pop and push (among others).

<code>
//command
alias myalias [1]

//infix variant
myalias = [1]
</code>

===executing aliases===

To execute an alias, you execute it like any other command. if I had an alias named '''myalias''', I would simply invoke ''''/myalias''' to execute it.

These aliases also have access to a class of special aliases. Those are the temporaries in which arguments are stored. There's also a useful variable named 'numargs' which tell you how many arguments were provided. The aliases containing the arguments are named arg. they are numbered and enumerated, starting from 1, so you'd use $arg1 to access the first argument. This does not start at 0, since arg0 is the command's name (arg0 is also not defined.. ever, nor included in numargs).

<code>
//prints all arguments to screen, one by one
//see the other comments for an explanation

print = [ //declares an alias named print
loop i $numargs [ //loops $numargs times, setting i to the current iteration
echo (getalias (concatword arg (+ $i 1)) //gets the value of the arguments, by accessing $arg1 $arg2 $arg3....
] //close loop
] //close print alias
print I like unicorns //should print I like unicorns on 3 separate lines
</code>

===push and pop===

Push and pop used to be two separate instructions, but since the advent of the new Cubescrpt interpreter/compiler (2.6.1), they have been merged into a single instruction. The syntax for this singular stack manipulation command is as follows.

push variable value body

The stack is automatically popped after execution

<code>
myalias = "candy"
push myalias "lollipops" [
echo $myalias
]
echo $myalias

//expected output
//lollipops
//candy
</code>

==Syntax==

Cubescript is not your typical scripting language. Cubescript is not the most flexible, or the best language, but it more than adequate for our needs and purposes. Cubescript draws its main inspiration from quakescript and from Lisp. It is therefor said that Cubescript contains many "Lispisms". Below is a summary of notable features/quirks.

* comments are denoted by //
* both newlines and ; denote the end of a call.
* newlines will automatically close of any strings you may have forgotten to. (you should not rely on this)
* substitutions are done through the use of $ and @ tokens, (See below)
* everything is a function which may take arguments. With the exception of setting an alias, infix notation does not exist
* there are no arrays or vectors, only lists.
* most implementations have a 25 word limit. This means commands can be invoked with up to 24 arguments

one liner example

<code>
alias hi [say "hi"; sleep 5000 [say "Hi again"]]
</code>

multi liner example

<code>
alias hi [
say "hi"
sleep 5000 [
say "Hi again"
]
]
</code>

it's obvious what the above code does, it'll make your character say hi, and wait 5 seconds before saying hi again.

indenting is done in levels, the Tabulator (TAB) key is usually used to indent the text. while not necessary, it tends to make it bigger, and more legible as seen in the above example (when you get to big stuff, you'll thank yourself for indenting it.

As a rule of thumb, pretty much only [ increases the indentation level. Also note, ", ] and ) can close each other, so make sure you close them off properly

==containers==

Containers in cubescript are of 3 specific types, "", () and [] - all of these have significant differences in operation and use

==="" container===

"" containers are used to store things EXACTLY as they are written, with a few small exceptions - in-text commands which are denoted by a preceding ^. They are as follows

* ^f#
** ^f# is used to colour text. # must be replaced by either a number or a capital letter (A-Z). r and s are special control characters which will restore and save the text's current colour respectively.
* ^n
** insert a '\n' character (newline/linefeed)
* ^t
** inserts a '\t' character (tabulator)
* ^"
** inserts a quote (")

===() container===

() containers are used mainly for logic/arithmetic operations. They are usually nested inside [] blocks, and unless they are nested inside []'s they're permanently substituted with their results.

For example - the following will turn into an infinite loop. The condition is initially evaluated and substituted with one and since 1 can never = 0, it's true forever more

<code>
i = 0
while (= $i 0) [i = (+ $i 1)]
</code>

the following code on the otherhand is devoid of such issues. Being nested inside the [] means it's not substituted and evaluated each cycle

<code>
i = 0
while [= $i 0] [i = (+ $i 1)]
</code>

===[] container===

This container is used for nesting, deferring execution of it's contents, deferring calculations and substitutions of () containers, and substitutions of aliases/variables written with a @ prefix (note several levels are needed to achieve this). [] containers are also the ONLY container capable of spanning multiple lines.

This is the most used container and due to it's properties, is ideal for creating aliases.

generally statements in cubescript can't span multiple lines. If you should use this container and occupy several, the execution of the prior command continues exactly where this container finished off. This can be demonstrated with an if statement.

<code>
if 1 [
do
stuff
] [
do
other
stuff
]
</code>

==substitution==

there are two principle ways of substituting values in cubescript, the first is through the use of $ tokens, the second is through the use of @ tokens.

a very simple example:
<code>
myalias = 5
echo $myalias
</code>
myalias is substituted into the echo statement, so you should see 5 printed to the top-left of the screen

using the @ token would have also resulted in the same behaviour
<code>
myalias = 5
echo @myalias
</code>

There's a big difference between the two, the @ token can be used to concatenate stuff together, $ can't. @ is also substituted immediately up to the first level of nesting. (this can be incremented by using additional @ tokens, ie @@ for 2 levels of nesting). Do take note that too few @ tokens may cause a substitution to happen too late, and too many may likewise cause it to happen too early.

'''An example of use in a level 1 nest'''

<code>
myalias = "I am awesome"
mymenu = [guitext @myalias]
</code>
if you were to type /echo $mymenu, it should read: guitext "I am awesome"; using the $ token on the other hand

<code>
myalias = "I am awesome"
mymenu = [guitext $myalias]
</code>
typing /echo $mymenu should produce: guitext $myalias

'''An example of concatenation'''

as i mentioned, @ also allows you to concatenate stuff together, which could result in shorter and simpler scripts. It should be noted that this can also result in extreme obfuscation
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [ do [
echo $myalias@i
]]
</code>
this should print 5, 3.1415 and 2.481 respectively

the purely $ token equivalent
<code>
myalias0 = 5
myalias1 = 3.1415
myalias2 = 2.481

loop i 3 [
echo (getalias (concatword myalias $i))
]
</code>

'''Lookup of a Lookup'''

There are two ways to look up multiple things; the first is by encasing it inside 'getalias', the second involves using multiple lookup tokens. There is a caveat with the second method, while it works on more types, it's only available in sandbox as of 2.6.1.

All 3 of the below examples should print "victory!"
<code>
alias1 = "alias2"
alias2 = "alias3"
alias3 = "victory!"

//the first method
echo (getalias (getalias $alias1))

//the second method; 2.6.1
echo $$$alias1

//to show compatibility with @
do [
echo $$@alias1
]
</code>

==Branching/Decisions==

Decisions are based on 6 key commands, '''if''', '''?''', '''cond''', '''case''' (integer), '''casef''' (float) and '''cases''' (string). There are also other ways to do this. For example you might be able to easily query something about an object, where it's obviously unique. You would then execute an alias whose name has this unique bit attached onto the end. This is an advanced method and is generally not recommended.

===if and ?===

Arguments: Cond True False

Unlike most other languages, cubescript's '''if''' contains an implicit else, in short we do not have an else statement. The provided condition is true if it ends up as a series of alpha numerics, or in the case of a number, as a value other than 0.

<code>
myalias1 = 5
myalias2 = "woot"

//if else-if else
if $myalias1 [
echo "myalias1 is true"
] [
//this shows the alpha numerics case
if $myalias2 [
echo "myalias1 is false and myalias2 is true"
] [
echo "myalias1 is false and myalias2 is false"
]
]
</code>

'''?''' acts exactly the same way, but there's one HUGE difference. '''?''' does not execute the chosen result.

<code>
//an example of where ? can be used where if would fail
items = 1
echo (format "You are carrying %1 item%2." $items (? (= $items 1) "" "s"))
</code>

===cond===

basically you provided a several pairs of arguments, the first half of the pair is the condition, and the second is the result. To put it in a programming perspective, this is like creating a long line of if else's together. Execution stops when the first condition is matched. Should you place several conditions where more than one may be true at any one time, only the first will be executed.

The following example assumes you have a light entity selected

<code>
lightstrength = [
cond [< (ea 0) 0] [
echo "It's like a black hole!"
] [= (ea 0) 0] [
echo "Blindlier than science!"
] [< (ea 0) 8] [
echo "It's weaker than Billy's night light!"
] [< (ea 0) 32] [
echo "Nice night light you got there"
] [< (ea 0) 96] [
echo "It's like a lamp, but it's not a lamp"
] [< (ea 0) 512] [
echo "By Jove! I can actually see the ground!"
] [>= (ea 0) 512] [
echo "Dark places are icky, don't you agree?"
]
]
</code>

===case===

This works similar to switches in most programming languages. The biggest difference is that you can't break out, nor evaluate multiple cases (aka, fallthroughs).

The first argument tells it which variable to use. The following arguments are given in pairs, the first half is the state, the second is the result.
If the state is a null type, it is considered the default case. The easiest way to generate a null type is to use ()

The following example requires a particles entity to be selected, it will print out what type it is. Do note that this example exceeds the 25 word limit.

<code>
parttype = [
pname = ""

case (ea 0) 0 [
pname = "Fire and Smoke"
] 1 [
pname = "Fire"
] 2 [
pname = "Smoke Plume"
] 3 [
pname = "Smoke"
] 4 [
pname = "Fountain"
] 5 [
pname = "Explosion"
] 6 [
pname = "Meter"
] 7 [
pname = "Vs Meter"
] 8 [
pname = "Text"
] 9 [
pname = "Flare"
] 10 [
pname = "Lightning"
] 11 [
pname = "Fire"
] 12 [
pname = "Smoke"
] 13 [
pname = "Water"
] 14 [
pname = "Snow"
] 15 [
pname = "Leaves"
] 32 [
pname = "Lens Flare"
] 33 [
pname = "Fixed Size Lens Flare"
] 34 [
pname = "Sparkly Lens Flare"
] 35 [
pname = "Sparkly Fixed Size Lens Flare"
] () [ //default
pname = "A very pretty albeit unsupported particle"
]

echo The particle you have selected is of type: $pname
]
</code>

===Naming===

another way of doing decisions/branches is to use paths with different names. This has limited usage though. in short it requires you to query some information to concatenate onto another word, which you would then execute. There are exceptions. Other than the number of results you can query, there is no limit here. A handy trick is to have several results execute the same alias, though this requires that they differ only slightly at most in operation.

<code>
//This example demonstrates the exception
//it requires you to have an entity selected
//This will conflict with showquickgui
newgui "particles" [guitext "It's like a random series of nothing"]
newgui "light" [guitext "SHINY!!!!"]
newgui "jumppad" [guitext "boing!"]

identify = [showgui (et)]
</code>

<code>
//shows a more standard example, at present this is exclusively used by edithud (see stdedit.cfg)
//this also requires you to have an entity selected.
identlight = [echo "it's so bright..."]
identdynlight = [identlight] // to demonstrate how different results can execute the same script
identjumppad = [echo "boing? boing!"]
identparticles = [echo "Please don't change it to a lens flare!"]

identify = [ if (enthavesel) [ident@(et)] [echo Select an entity first!]]
</code>

==Lists==

Ordered lists are the closest cubescript has to the likes of arrays. Their declaration is identical to any alias, as they are simply items in a string separated by white space. Using [] is recommended as the container of choice, since it allows you to use "" to include multi-word items in a list as a single unit as well as define the list over multiple lines. "" can also be used to define lists. An example can be inspected below.

<code>
//declares 2 equivalent lists of 3 elements
mylist1 = [one two "three four"]
mylist2 = "one two ^"three four^""

//prints the 3rd element
echo (at $mylist 2)
</code>

'''loops'''

There are at least 2 ways to loop through a list. The first method involves the use of looplist to iterate over it and the second the use of listlen to determine the list's length. The difference between using looplist and listlen is that you will not have a reliable way of determining an element's index and won't have to manually fetch the element from the list. Basically looplist is faster at the cost of some information and should be used in all cases where the index does not need to be known.
An example can be inspected below.

<code>
mylist = [
0
1
3.14159265359
2.71828182845
sqrt(-1)
1 //to demonstrate that the index cannot be determined reliably with looplist
]

//demonstrates looplist
looplist var $mylist [
echo number (listfind item $mylist [strcmp $var $item]) : $var
]

//demonstrates a loop + listlen combo
loop i (listlen $mylist) [
echo number $i : (at $mylist $i)
]
</code>

'''concatenation'''

Concatenation is pretty simple, albeit not very efficient. It is basically, setting the list to itself plus the additional item. This is of course best achieved through the concat commands.

<code>
mylist = [1 2 3 4 5 6 7 8 9 10]

//using concatword
mylist = (concatword $mylist " " 11)

//using format
mylist = (format "%1 %2" $mylist 12)

//using concat - we're also preparing it for pretty list
mylist = (concat $mylist 14)

//pretty list does add an item onto the list, but it changes the format dramatically and the new item is placed before the end
//it is ideal more so for making things pretty for presentation than concatenation
mylist = (prettylist $mylist 13)

//should print 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 14
echo mylist is $mylist
</code>

concat returns everything given to it as a singular item, spaces and all. Concatword ignores spaces and ""'s must be explicitly provided. Concat is therefor ideal to add lists together.

<code>
mylist1 = [1 2 3 4 5]
mylist2 = [6 7 8 9 10]
mylist3 = [11 12 13 14 15]
mylist4 = [16 17 18 19 20]
mylist5 = [21 22 23 24 25]
mylist6 = [26 27 28 29 30]
finallist = ""

//how concatword merged three lists
finallist = (concatword $mylist1 " " $mylist2 " " $mylist3)

//concat unlike the above does not require
finallist = (concat $finallist $mylist4 $mylist5 $mylist6)

echo (prettylist $finallist)
</code>

'''finding'''

there are two ways to find things, the first is to use listfind, and the second is to loop through the list. Both are demonstrated in the example below

<code>
mylist = [
"Jack"
"Jane"
"Joseph"
]

//This is an example of looking for a single element, note that this variant of...
//strcmp unlike its C counterpart returns 1 when strings are equal
//in this example, a 0 should be printed at the top of your screen - listfind returns the index
echo (listfind f $mylist [strcmp $f "Jack"])

//In this example, -1, as Jill is not in the list
echo (listfind f $mylist [strcmp $f "Jill"])

//in this example, we want to find anything which contains an e and add it into a list
results = ""
looplist var $mylist [
if (>= (strstr $var "e") 0) [
results = (concatword $results "^"" $var " ^"")
]
]

//this should print: Jane Joseph
echo $results
</code>

=List of commands=

==General==

The following commands are quite often used in a lot of scripts.

* alias N B
** creates an alias named N with body B, the intext version is denoted as N = B (equivalent to alias N B)
* at S I
** returns the Ith element in string S, note that counting starts from 0. If it's out of range, "" is returned
* getalias A
** returns the value of A. this also does not produce a warning should an alias be undeclared, nor complains when fetching built in variables.
* if C T F (F is optional)
** if condition C is true, execute T, otherwise F is executed
* listlen S
** returns the amount of elements in list S
* loop V N B
** loops N times, and aliases the current iteration to V; B is executed every iteration.
* result S
** returns the string, useful when aliases need to be executed
* rnd N L
** chooses a random number between 0 and N-1 (inclusive). L sets the lower limit. eg rnd 12 7 will return either 7 8 9 10 or 11
* sleep N B
** executes B after a delay of N milliseconds. NOTE: even if N is <= 0, it'll still wait till the next frame before executing it
* while C B
** executed B while C is true. NOTE: surround C in a [] container, or you risk an infinite loop due to the condition not being reevaluated.

==Map Configuration==
'''''ONLY APPLIES TO FPSGAME'''''

The following commands are useful in level only aliases

*triggerstate
*level_trigger
**level trigger is invoked as level_trigger_1 = [] as an example, the end number is the 4th number in the mapmodel's strings
*level_base
**Used to give bases names in capture mode. This is unfortunately unused in PAS

==Binds==

The following commands are useful in binds.

*onrelease

==Gui Creation==

For newui, please see [[new menu editing]]

These commands are used to create various menus.

* cleargui
* guibar
* guibutton
* guicheckbox
* guifield
* guikeyfield
* guiimage
* guilist
* guirolloveraction
* guirollovername
* guislider
* guilistslider
* guinameslider
* guistayopen
* guitab
* guitext
* guititle
* guistrut
* newgui

==Comparisons==

The functions here can change the values, or return a logical comparison
for all intents and purposes, the C version of booleans apply here; values not equal to 0 are true - and functions that return true return 1

===Integer Arithmetic===

* + A B
** returns the value of the numbers added together
* <nowiki>*</nowiki> A B
** returns the result of multiplying A and B
* - A B
** returns the value of A - B
* = A B
** returns true of the two are equal
* != A B
** returns true if the two aren't equal
* <nowiki><</nowiki> A B
** returns true if A is less-than B
* <nowiki>></nowiki> A B
** returns true if A is greater-than B
* <nowiki><=</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* ! A
** if the argument is false, it returns true
* &&
** returns true if all arguments are true
* ||
** returns true it at least one argument is true
* div A B
** returns the value of A divided by B
* mod A B
** returns the modulus of the two arguments
* min
** returns the lowest valued argument of all provided arguments
* max
** returns the highest valued argument of all provided arguments

===Bitwise Integer Operations===

* ^ A B
** returns the value of A xor B ie (^ 8 4) is 12 - (^ 12 4) is 8
* & A B
** returns the value of the bits both A and B have
* | A B
** returns the value of the bits either A or B have
* ~ A
** returns the inverted bitwise version of A ie (& (~ 128) 255) is 127
* ^~ A B
** xor;s the arguments after applying an inversion on B
* &~ A B
** and's the arguments after applying an inversion on B
* |~ A B
** or's the arguments after applying an inversion on B
* <nowiki><<</nowiki> A N
** shifts A N bits
* <nowiki>>></nowiki> A N
** shifts A -N bits

===Floating Point Arithmetic===

Generally these just have an -f suffix

* +f A B
** returns the value of the numbers added together
* <nowiki>*f</nowiki> A B
** returns the result of multiplying A and B
* -f A B
** returns the value of A - B
* =f A B
** returns true of the two are equal
* !=f A B
** returns true if the two aren't equal
* <nowiki><f</nowiki> A B
** returns true if A is less-than B
* <nowiki>>f</nowiki> A B
** returns true if A is greater-than B
* <nowiki><=f</nowiki> A B
** returns true if A is less-than-or-equal-to B
* <nowiki>>=f</nowiki> A B
** returns true if A is greater-than-or-equal-to B
* divf A B
** returns the value of A divided by B
* modf A B
** returns the modulus of the two arguments
* minf
** returns the lowest valued argument of all provided arguments
* maxf
** returns the highest valued argument of all provided arguments

===Strings===

* =s A B
** returns 1 if the string matches, 0 otherwise
* !=s A B
** returns 0 if the string matches, 1 otherwise
* <nowiki><s</nowiki> A B
** returns true if the C strcmp returns less-than 0
* <nowiki>>s</nowiki> A B
** returns true if the C strcmp returns greater-than 0
* <nowiki><=s</nowiki> A B
** returns true if the C strcmp returns less-than-or-equal-to 0
* <nowiki>>=s</nowiki> A B
** returns true if the C strcmp returns greater-than-or-equal-to 0
* strcmp A B
** returns 1 if the string matches, 0 otherwise (unlike the C version with returns the disparity)
* strstr H N
** returns the position of N in H - otherwise -1 is returned
* strlen S
** returns the length of the string
* strreplace S O N
** replaces all instances of O inside string S with N

==String/text formatting==

These commands are used to format aliases which are normally huge bits of text

* concat C
** everything you type after will be returned; with expressions and substitutions performed
* concatword C
** the next 25 arguments will be executed and subsequently concatenated without any spaces between them
* format F S1 S2 S3 S4 S5 S6 S7 S8 S9
** F is a string containing %# tokens, format substitutes the arguments with their respective %# tokens (ie: S5 will replace %5)

=See Also=

*[[map_config|Map Configuration]]

RPG tutorial

2011-11-16T12:31:20Z

Hirato: /* 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

Development

2011-11-16T12:02:22Z

Hirato: /* Important Revisions */

We've no intention of releasing development, or testing versions. alas we have a stable development repository available. Using it is not meant for the faint of heart, we (by that I mean Hirato) may occasionally break something.

Obtaining development versions is useful for testing, and it allows users (like yourself) to test out that latest and greatest of the feature set.

On a side note, we use SVN for our development repository needs.

and for those in search of the Eisenstern derived, "Master Chef Ogro" RPG, simply substitute 
http://www.svn.kids.platinumarts.net/32pas32/trunk/ 
for 
http://svnrpg.kids.platinumarts.net/kidsrpg

=Main Windows SVN How To=

'''''Using Tortoise SVN'''''

One of the easiest and most popular ways of using SVN on Windows is through the program Tortoise SVN here [http://tortoisesvn.net/downloads] The top link under Windows 32 is what most people want to get. After installing Tortoisesvn, create a folder and call it PAS. Right click on the folder and select SVN Checkout. Under where it says URL enter:

Main Version http://www.svn.kids.platinumarts.net/32pas32/trunk/ 

Under where it says checkout directory enter where you put the PAS folder. You can click on those three dots to navigate to it. After that hit okay and you should start downloading Sandbox to the PAS folder. Once you've finished you'll need to compile the source code to get fully up to date, please see our [[Compiling_the_source_code]] instructions for that. To update right click the PAS folder and select update. If you delete a file by accident you can just select update to restore it :)

=Main POSIX system SVN How To=

'''''Using the trusty old, Command Line'''''

The first step would be to obtain an SVN client, in any popular Linux distribution this can be found in the "subversion" package, OS X users should find a copy bundled with the xcode family of tools for their system.

Now simply fire up a terminal window, we recommend executing the following command in your home directory or a dedicated directory.
feel free to substitute sandbox with an alternative destination.

<code>
svn co http://www.svn.kids.platinumarts.net/32pas32/trunk sandbox
</code>

If you'd like to checkout the other branches as well (currently only sandboxlite) execute the following command instead

<code>
svn co http://www.svn.kids.platinumarts.net/32pas32 sandbox
</code>

the following are some common and useful commands you should get used to if you're planning to use the SVN, for all of them you may pass --help for further details

<code>
svn update # updates to the latest version available on the repository
svn revert --recursive # reverts any changes you've made to your checkout
svn diff -r BASE > mypatch.diff # generates a patch from your changes to the SVN you can send to us
</code>

=Gui Interfaces=

A well designed GUI can ease the effort that may other wise be required to commit changes, access the repository, do diff (differences between two versions of a file, also called a patch). GUIs also take a bit of time getting used to, as they often have different and confusing ways of defining a repository and checking it out

==kdesvn==
[[image:kdesvn.png|left|thumb|200px|A screenshot of the context menus in KDE 3.5]]
[[image:kdesvn1.png|right|thumb|200px|A screenshot of the checkout dailogue in KDE 3.5]]
'''Konqueror'''

A KDE svn client, integrates with konqueror to allow easy manipulation of svn directories via right click context menus and possibly other methods.

to use kdesvn (our way), install it and launch konqueror. type ~ into the location bar.

now, create a new folder named 'sandbox' or 'pas' or whatever.

enter the directory then right click or right click the directory, and then hover your cursor over 'actions', then 'Subversion', kdesvn should be in suffixing brackets. click 'checkout from a repository'

make sure the destination directory is as you want it. Enter http://www.svn.kids.platinumarts.net/32pas32/trunk/ into the 'Enter URL' field. Make sure that HEAD is selected of the below options, and that is recurses directories. Untick 'append source url name to folder' as I already made you create a valid directory

congrats, once it fetches about 80 MB, you have the latest dev of sandbox. just periodically right click the folder, and follow the context menus to update it. you can also do diffs, revert your changes and review logs through the simple to use context menu.

'''Stand alone GUI'''

using the Standalone GUI is simple and easy, simply start it up (ALT-F2, and enter kdesvn into the box that appears), click on 'Subversion' at the top bar, hover it over 'General', and then click, 'Checkout a Repository'. Alternatively you can click the button 3rd from the right in the bar, it should have the tooltip, 'Checkout a Repository'

in the window that appears, click the folder icon and select a directory to check it into, the 'append source url name to folder' is optional, depending on where you chose. somewhere in your home folder (~) is recommended. once again, enter http://www.svn.kids.platinumarts.net/32pas32/trunk/ into the URL field.

and you're done. note, you may wish to tick the 'load last opened url on start' in the 'settings' area of the main gui.

==Rapid SVN==

Works on both Linux and Windows. Not quite as easy to use as the SVN programs that integrate with the browsers but it is another alternative.

==eSvn==

===Checking out the repo===

===What else is there to do===

===File Mapping===

=Important Revisions=
This is mostly for people who want to get 'release' versions from the repos.
*3359 - Final 2.7.1 package
*3253 - Final 2.7.0 build
*2774 - Final 2.6.1 build
*2655 - Final 2.6.0 build
*1523 - Final 2.5.0 build
*1165 - Final 2.4.0rc1 build
*760 - Final 2.3.0 Release build
*446 - Final 2.2.0 release
*441 - 2.2.0 fileplanet release
*~200 - 2.1.0 release (sorry there were a few problems that make it difficult to be more accurate)
*89 - 2.0.0 release

RPG todo

2011-11-05T09:51:58Z

Hirato: /* Script */ I-i-implemented!

=Gameplay=
* hotkeys
* special item properties
** money (constant value for all purposes)
** cursed status
** unidentified status
*** hide true power or make it a lot less useful?
* (maybe?) character generation
* looting and trading... hardcode references "loot" and "trade"?
* sneaking/stealth
** light and visibility
** silhouettes and light levels?
** stealing
* proper friendly fire protection
** 0 - no protection (default)
** 1 - prevents you from hurting yourself
** 2 - 1 + prevents you from hurting allies
** 3 - allows injury to hostile characters only
* spell types
** movement (paralysis counters)
** vocal (silence counters)

=Logic=
* the consume use case for books and potions.
* statusgroups on items
** temporary spells that alters the properties of the weapon
** multiple at once with different targets.
* temporary spell effects for wielded items,
** multiple status effects on a single use, separate chargeflags, multiplier, duration and element.
** make sure to use each for the right purpose
* Projectiles
** improve ricochet, gravity related stuff is funky
* target types
** cone
** self-area/multi
* status types
** dispel - should work on individual effects
** silence
** paralysis/stun
* Expose a tonne of constants to Cubescript for configuration at the game maker's discretion. These include leveling and power curves
* arbitrary trigger bounding box scales

=GUI=
* inventory
** item examination
* status effects
* trade
* stats
* crafting
* journal
* newui variants

=Recipes=
* (maybe) allow in game apparatuses to act as a catalyst
** (maybe) several catalysts and ingredients list? or just duplicate and alter the recipe?

=AI=
* queued prioritised actions
** most important done first
** multitasking
* waypoints
** randomness
** state - don't favour waypoints which are in use
* ai tags
** identify purpose and effect of entities in game world for the AI (parsing the script for these is simply not practical)
*** alternatively use simpler more specific types, such as "door", "container", "portal" and "mover" as opposed to a singular "object"

=Cutscenes=
* create a cutscene variant which can't be skippped (maybe)
* some sort of skipping bar (1000 ms?) to prevent accidental skips

=Renderer=
* particles for active spell effects
* render attachments/equipment
* animations for weapons
** generic animations, unarmed strike, melee strike, bow shoot, gun shoot, etc

=Journal=
* quests
* log entries
* sorting and filters

=Sound=
* sounds while charging spells
* sounds for projectile firing, travel and death
* sounds for active statusgroups
* (maybe) voiced dialogue

=I/O=
* flat file export of current script/data definitions (maybe)
** couple with ingame menus for realtime modification (maybe)
* better range checks and protection
* save and restore AI directives

=Particles=
* set particle effects for entity afflicted status effects
* vary spawned amount of particles depending on distance (few when close, full amount when far away)
* explicit variable for setting waypoint drawing distance

Platinum Arts Sandbox Free 3D Game Maker:Community Portal

2011-11-01T03:32:11Z

Hirato: Reverted edits by HughLacasse (Talk) to last revision by Hirato

Possible upcoming events. Please contact us if you are interested!

* Kid friendly RPG
* Water Waters - DM type game with water guns and water balloon bazookas!
* Kart mode into an actual racing game.
Also Sandbox is being used in more and more schools! The goal is to try to get Sandbox into as many schools as we can, and the more schools and kids using it the better! Any help that you can give us is much appreciated!

Packaging guide

2011-10-30T09:03:25Z

Hirato: /* invalid substitutes for "map" */ tweaks

This is mostly a set of guidelines for people packaging up their maps for redistribution among peers in the sandbox community

it's important to note that if you intend to distribute more than the ogz itself, that you're to use zip archives, or tar archives with either bzip or gzip compression. (non-windows platforms support this natively, for windows, use 7zip)

rar archives are not to be used, simply for cross platform concerns (linux supports it poorly, and OSX I believe doesn't support it at all)

=What to include in the zip=

==the basic zip structure==
[] indicates a folder, - the level.

* [packages]
* - [base]
* - - map.ogz
* - - map.cfg
* - - map-art.cfg
* - - map.jpg
* - - map_big.jpg

if it's just a map, feel free to omit the base and package directories form the hierarchy.

note that other users do NOT want to pick through you archive to extract everything, so the first folder should always be packages, not the second! 
it's less painful that way, and allows some operating systems to add the files, instead of overwriting the whole packages directory.

==invalid substitutes for "map"==

When one names his map, there's a few things you can't do, you're not allowed to name the map as to...

* contains any brackets (this is includes braces and square brackets)
* contain any punctuation (the only exception is the fullstop signaling the file extension)
* contain greater than or less than signs, the engine WILL ignore them

Normal social standards also apply, expletives are not to be present in map names and ridicule directed at anyone isn't to be in the name.

==taking the map.jpg screenshots==

'''Note: png, bmp and tga are also allowed, but not recommended (the engine will identify the extension automatically)'''

map.jpg
# go into windowed mode and resize the window to 512x512 or 1024x1024
# press Ctrl-F12 to take the screenshot
# open the screenshot in the gimp or photoshop and resize it to either 512x512 or 256x256 and save it into packages/base, whilst substituting map for the map's name (note that resolutions that are not 2^n (where n is an integer) display oddly, and mapshots above 512^512 won't be accepted)
## you might like to play with /fov to try a different/better view for the screenshot

map_big.jpg
# use your standard resolution in sandbox, such as 1024x768 (1280x960 or above is suggested, note that if the map's included in sandbox, it won't be allowed past 1280x960)
## NOTE: 2.3.3 and later (development versions), scale the images based on size, so feel free to use 16:9, anything older requires you to use 4:3.
# ctrl-F12 to take a screenshot
# open the screenshot in the gimp or photoshop and save it to packages/base as map_big.jpg, whilst substituting map for the map's name

==Custom art==

custom art created by you is to be placed in either 1 or more of the following 3 directories

* [packages]
* - [my_name]
* - [models]
* - - [my_name]
* - [sounds]
* - - [my_name]

packages/my_name is to be used for textures, music, and other graphical data 
packages/models/my_name is to be used for hosting models, and any relevant skins, which aren't going to be used as regular textures 
packages/sounds/my_name is to be used for any custom SFX you wish to add

the above assumes of course, you're including your art, while including the art of another, you can either but them in a sub directory with THEIR alias, or keep them with your files. 
<big>just don't forget to give proper attribution within the readmes</big>

Packaging guide

2011-10-30T09:00:32Z

Hirato: let's not encourage use of the rar format ;)

This is mostly a set of guidelines for people packaging up their maps for redistribution among peers in the sandbox community

it's important to note that if you intend to distribute more than the ogz itself, that you're to use zip archives, or tar archives with either bzip or gzip compression. (non-windows platforms support this natively, for windows, use 7zip)

rar archives are not to be used, simply for cross platform concerns (linux supports it poorly, and OSX I believe doesn't support it at all)

=What to include in the zip=

==the basic zip structure==
[] indicates a folder, - the level.

* [packages]
* - [base]
* - - map.ogz
* - - map.cfg
* - - map-art.cfg
* - - map.jpg
* - - map_big.jpg

if it's just a map, feel free to omit the base and package directories form the hierarchy.

note that other users do NOT want to pick through you archive to extract everything, so the first folder should always be packages, not the second! 
it's less painful that way, and allows some operating systems to add the files, instead of overwriting the whole packages directory.

==invalid substitutes for "map"==

When one names his map, there's a few things you can't do, you're not allowed to name the map as to...

* contains any brackets (this is includes braces and square brackets)
* contain any punctuation (the only exception is the fullstop signaling the file extension)
* contain greater than or less than signs, the engine WILL ignore them
* contain forward or back slashes

just for social standards, mapnames aren't allowed to
* contain any form of prejudice against a group of people
* contain any "swear" words

==taking the map.jpg screenshots==

'''Note: png, bmp and tga are also allowed, but not recommended (the engine will identify the extension automatically)'''

map.jpg
# go into windowed mode and resize the window to 512x512 or 1024x1024
# press Ctrl-F12 to take the screenshot
# open the screenshot in the gimp or photoshop and resize it to either 512x512 or 256x256 and save it into packages/base, whilst substituting map for the map's name (note that resolutions that are not 2^n (where n is an integer) display oddly, and mapshots above 512^512 won't be accepted)
## you might like to play with /fov to try a different/better view for the screenshot

map_big.jpg
# use your standard resolution in sandbox, such as 1024x768 (1280x960 or above is suggested, note that if the map's included in sandbox, it won't be allowed past 1280x960)
## NOTE: 2.3.3 and later (development versions), scale the images based on size, so feel free to use 16:9, anything older requires you to use 4:3.
# ctrl-F12 to take a screenshot
# open the screenshot in the gimp or photoshop and save it to packages/base as map_big.jpg, whilst substituting map for the map's name

==Custom art==

custom art created by you is to be placed in either 1 or more of the following 3 directories

* [packages]
* - [my_name]
* - [models]
* - - [my_name]
* - [sounds]
* - - [my_name]

packages/my_name is to be used for textures, music, and other graphical data 
packages/models/my_name is to be used for hosting models, and any relevant skins, which aren't going to be used as regular textures 
packages/sounds/my_name is to be used for any custom SFX you wish to add

the above assumes of course, you're including your art, while including the art of another, you can either but them in a sub directory with THEIR alias, or keep them with your files. 
<big>just don't forget to give proper attribution within the readmes</big>

Platinum Arts Sandbox Free 3D Game Maker:Community Portal

2011-10-25T05:22:05Z

Hirato: Reverted edits by IsabelleBarry (Talk) to last revision by Hirato

Possible upcoming events. Please contact us if you are interested!

* Kid friendly RPG
* Water Waters - DM type game with water guns and water balloon bazookas!
* Kart mode into an actual racing game.
Also Sandbox is being used in more and more schools! The goal is to try to get Sandbox into as many schools as we can, and the more schools and kids using it the better! Any help that you can give us is much appreciated!

RPG tutorial

2011-10-20T02:10:01Z

Hirato:

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, the maps require a version of sandbox newer than 2.7.0

Platinum Arts Sandbox Free 3D Game Maker:Community Portal

2011-10-20T02:01:32Z

Hirato:

Possible upcoming events. Please contact us if you are interested!

* Kid friendly RPG
* Water Waters - DM type game with water guns and water balloon bazookas!
* Kart mode into an actual racing game.
Also Sandbox is being used in more and more schools! The goal is to try to get Sandbox into as many schools as we can, and the more schools and kids using it the better! Any help that you can give us is much appreciated!

Contact The Team

2011-10-20T01:58:37Z

Hirato: Reverted edits by Markchristaen (Talk) to last revision by Hirato

Interested in getting into contact with us? Here are a few quick easy ways to do so :)

== Developer Chatroom ==

The easiest way of finding us is to join our developer chatroom.

'''NOTE: KIDS MUST HAVE PARENTAL PERMISSION TO JOIN AND WE CANNOT BE RESPONSIBLE FOR THINGS SAID IN THERE. ALSO WE ARE FREQUENTLY IDLE IN THE CHATROOM WORKING ON SANDBOX, IF YOU EXPECT A RESPONSE PLEASE WAIT'''

You can simply [http://sandboxgamemaker.com/irc/irc.html click here] or if you already have an irc client it is [irc://irc.oftc.net/sandbox irc.OFTC.net #Sandbox] In addition you can try our new [http://widget.mibbit.com/?settings=ca48890d9db5ad90e8d98c1d1d3ce14b&server=irc.oftc.net&channel=%23sandbox&noServerTab=false&autoConnect=true mibbit link].

If you don't want to use your webbrowser to connect to the chatroom, and instead want to use a standalone program, then you can use Xchat at http://silverex.org This is the free version of xchat, as the main version of xchat has a 30 day trial. 
Instructions: 
1)In the xchat menu to go the network list 
2)Find OFTC or add irc.OFTC.net then select edit 
3) In favorite channels add #sandbox and
set it to autoconnect 
4) With OFTC still highlighted, hit connect and join us :D 

== Forums ==

Obviously we check this on a regular basis so feel free to post there. http://forum.sandboxgamemaker.com

== E-mail ==

You
can contact us at PlatinumArts@gmail.com PLEASE NO TECHNICAL SUPPORT QUESTIONS. PLACE TECHNICAL SUPPORT QUESTIONS IN THE FORUM OR CHATROOM

Platinum Arts Sandbox Free 3D Game Maker:Community Portal

2011-10-20T01:58:36Z

Hirato: Reverted edits by MacyWales (Talk) to last revision by BradleyBriggs

Possible upcoming events. Please contact us if you are interested!

* Kid friendly RPG
* Water Waters - DM type game with water guns and water balloon bazookas!
* Kart mode into an actual racing game.
*[http://www.proposable.com proposal software]
Also Sandbox is being used in more and more schools! The goal is to try to get Sandbox into as many schools as we can, and the more schools and kids using it the better! Any help that you can give us is much appreciated!

Main Page

2011-10-20T01:57:43Z

Hirato:

'''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]]
* [[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 ==

*[[Tutorials List | Text Tutorials List]]
*[[Video Tutorials List]]

RPG script

2011-10-13T07:11:46Z

Hirato:

=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

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=

RPG script

2011-10-13T05:46:50Z

Hirato: /* Loops */

'''WARNING:''' Information here is incompatible with 2.6.1 and earlier

=How things work=

The system is stack based. Basically when scripts are executed the stack is pushed, the script executed and then popped. This allows the system/user to define additional lookups on the stack. There are two types of references, regular and temporary references, both serve different purposes, and the stack is searched in reverse for them.

The only notable difference between them is how they're set. Regular lookups search the whole stack for an existing reference to modify, temporary lookups only search the top of the stack for an existing instance and create one if it doesn't exist. This effectively allows temporary references to ghost references in the lower stack; In other words with temporary references, you can have two references with the exact same name which point to two distinctly different things.

Users cannot define temporary lookups. In addition most commands require references to function.

<code>
r_loop_maps ref [
//ref here refers to the current map
r_loop_ents ref ref [
//ref here refers to the current entity, the map version is ghosted but not lost
//now lets do something productive like killing everyone but the player
if (! (r_matchref ref player)) [r_kill ref player]
]
]
</code>

==Reserved lookups==
Since the RPG works with named lookups, there are several named you should never explicitly define or set. There's no rule against doing so, but keep in mind very bad things may happen if you do. They are as follows.

* player - a reference to the player
* hover - a reference to whatever the player's cursor is hovering over (even nothing)
* curmap - a reference pointing to the current map
* talker - (dialogue) a reference to whoever is talking to the player

The following can be overwritten, but exercise due caution when doing so. They are defined when the RPG explicitly calls character, item and map scripts (albeit using temporary references).

* self - in map or ent scripts, refers to the invokee
* actor - when scripts are executed, this refers to the entity who invoked them.
* item - during item scripts this refers to the selected item

=Loops=

There are 4 loops, each iterate over certain things, they are as follows

'''Command:''' r_loop_maps reference body

Makes a temporary reference named 'reference', and has it reference each of the maps in turn on which it executes the body.

'''Command:''' r_loop_ents map_reference reference body 
'''map_reference:''' must reference a map

Makes a temporary reference named 'reference', and has it reference each of the entities that exist on the map pointed to by map_reference.

'''Command:''' r_loop_aeffects map_reference ent_reference reference body 
'''map_reference:''' must reference a map
'''ent_reference:''' must reference an entity if bounds checking is desired

Makes a temporary volatile named reference that iterates over all area effects on the map_reference that afflicts ent_reference (if provided), loops over all area effects otherwise

'''Command:''' r_loop_inv ent_reference reference body 
'''ent_reference:''' must reference either a character (such as the player) or an object (such as a chest)

Makes a temporary reference named 'reference', and has it reference each of the items that exist in the entity's inventory

'''Command:''' r_loop_equip ent_reference reference body 
'''ent_reference:''' must reference a character

Makes a temporary volatile reference named 'reference', and has it reference each of the items the entity has equipped. you sohuld avoid unequipping anything while doing this

'''Command:''' r_loop_veffects ent_reference reference body 
'''ent_reference:''' must reference an entity

Makes a temporary volatile reference named 'reference', and has it reference each of the status effects that plagues the provided entity

=Commands=

=Examples=

RPG configuration

2011-10-13T05:34:28Z

Hirato: /* Containers */

=Intro=
The definitions are stored in a series of sub directories in your game's directory. The directory itself will typically share the name of the definitions it contains, ie, one containing critter definitions will be called critters.

The game's directory itself will share its name with a .cfg file placed along side it, this CFG file allows the RPG module to ascertain the game's presence and subsequently load it, as well as define other properties. There is a base directory included to help you set things up.

If you require help in setting things up, please consult the first part of the [[RPG_tutorial tutorial]].

=Game configuration=

the cfg that lives along the game's directory defines several very important things. It associates maps with scripts and mapflags, defines the first map and all sorts of other properties as well as the game's HUD.

Currently not implemented is the means to adjust the stat gradients.

Available variables at present are
* firstmap - the first map that is loaded if one isn't specified
* gameversion - game version
* compatversion - oldest game version the game is compatible with (for patches)

Available commands are
* r_preparemap map script flags

=Notes and tips=

Firstly slots, each and every single slot has a companion command with a _get (usually takes no arguments) suffix that will return its value.

Secondly, you are going to be modifying the definitions quite a lot and perhaps even tweak them a lot in a very short space of time, there's a command named '''r_rehash''' available to facilitate your testing. Make sure to save your map and game before using it.

Thirdly, if you are going to duplicate definitions for the purpose of making derivatives, use the '''include''' command to execute that definition. Include is executed relative to your game's directory eg. include scripts/1 will execute data/rpg/games/mygame/scripts/1.cfg

=Scripts=
==Commands==
==Slots==

=Particle Effects=
==Commands==
==Slots==

=Status groups=
==Commands==
==Slots==

=Items=
==Commands==
==Slots==

=Ammo groups=
==Commands==
==Slots==

=Critters=
==Commands==
==Slots==

=Factions=
==Commands==
==Slots==

=Obstacles=
==Commands==
==Slots==

=Containers=
==Commands==
==Slots==

=Platforms=
==Commands==
==Slots==

=Triggers=
==Commands==
==Slots==

=Mapscripts=
==Commands==
==Slots==

=Recipes=
==Commands==
==Slots==

=Global Variables=

=Tips=

RPG configuration

2011-10-13T05:34:13Z

Hirato:

=Intro=
The definitions are stored in a series of sub directories in your game's directory. The directory itself will typically share the name of the definitions it contains, ie, one containing critter definitions will be called critters.

The game's directory itself will share its name with a .cfg file placed along side it, this CFG file allows the RPG module to ascertain the game's presence and subsequently load it, as well as define other properties. There is a base directory included to help you set things up.

If you require help in setting things up, please consult the first part of the [[RPG_tutorial tutorial]].

=Game configuration=

the cfg that lives along the game's directory defines several very important things. It associates maps with scripts and mapflags, defines the first map and all sorts of other properties as well as the game's HUD.

Currently not implemented is the means to adjust the stat gradients.

Available variables at present are
* firstmap - the first map that is loaded if one isn't specified
* gameversion - game version
* compatversion - oldest game version the game is compatible with (for patches)

Available commands are
* r_preparemap map script flags

=Notes and tips=

Firstly slots, each and every single slot has a companion command with a _get (usually takes no arguments) suffix that will return its value.

Secondly, you are going to be modifying the definitions quite a lot and perhaps even tweak them a lot in a very short space of time, there's a command named '''r_rehash''' available to facilitate your testing. Make sure to save your map and game before using it.

Thirdly, if you are going to duplicate definitions for the purpose of making derivatives, use the '''include''' command to execute that definition. Include is executed relative to your game's directory eg. include scripts/1 will execute data/rpg/games/mygame/scripts/1.cfg

=Scripts=
==Commands==
==Slots==

=Particle Effects=
==Commands==
==Slots==

=Status groups=
==Commands==
==Slots==

=Items=
==Commands==
==Slots==

=Ammo groups=
==Commands==
==Slots==

=Critters=
==Commands==
==Slots==

=Factions=
==Commands==
==Slots==

=Obstacles=
==Commands==
==Slots==

=Containers=
==Commands==
==Slots==

=Platforms
==Commands==
==Slots==

=Triggers=
==Commands==
==Slots==

=Mapscripts=
==Commands==
==Slots==

=Recipes=
==Commands==
==Slots==

=Global Variables=

=Tips=

RPG

2011-10-13T04:47:20Z

Hirato: /* 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_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.

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

2011-10-12T17:24:27Z

Hirato: a little extra for my fans ;)

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

=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, the maps require a version of sandbox newer than 2.7.0

RPG tutorial

2011-10-12T17:13:56Z

Hirato: /* 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=

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

=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.

RPG tutorial

2011-10-12T16:32:40Z

Hirato: /* Part 7 */ puzzles!

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

=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)
]
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>

RPG tutorial

2011-10-09T16:00:27Z

Hirato: /* Part 6 */ finish 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

=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 puzzle to open a door as well as overriding the HUD

RPG tutorial

2011-10-09T12:03:23Z

Hirato: /* 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=

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

=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>

Spawn this in the back of the dedicated room in the dungeon. All that is left to do now is to add relevant dialogue paths to Bob and record your progress via global variables.

REST OF TUTORIAL HERE

==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

=Part 7=

This part of the tutorial involves the creation of a basic puzzle to open a door as well as overriding the HUD

RPG tutorial

2011-10-09T11:13:04Z

Hirato: /* 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

=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_attack self actor
]
]

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

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

r_script_signal collide [
if (!= (r_get_faction self) (r_get_faction actor)) [
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>

Spawn this in the back of the dedicated room in the dungeon. All that is left to do now is to add relevant dialogue paths to Bob and record your progress via global variables.

REST OF TUTORIAL HERE

==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

=Part 7=

This part of the tutorial involves the creation of a basic puzzle to open a door as well as overriding the HUD

RPG todo

2011-10-09T10:50:07Z

Hirato: /* Logic */

=Script=
* Timers
** copy reference table
** countdown to 0 before executing.
** update every frame, but execute only outside of cutscenes.

=Gameplay=
* hotkeys
* special item properties
** money (constant value for all purposes)
** cursed status
** unidentified status
*** hide true power or make it a lot less useful?
* (maybe?) character generation
* looting and trading... hardcode references "loot" and "trade"?
* sneaking/stealth
** light and visibility
** silhouettes and light levels?
** stealing
* proper friendly fire protection
** 0 - no protection (default)
** 1 - prevents you from hurting yourself
** 2 - 1 + prevents you from hurting allies
** 3 - allows injury to hostile characters only
* spell types
** movement (paralysis counters)
** vocal (silence counters)

=Logic=
* the consume use case for books and potions.
* statusgroups on items
** temporary spells that alters the properties of the weapon
** multiple at once with different targets.
* temporary spell effects for wielded items,
** multiple status effects on a single use, separate chargeflags, multiplier, duration and element.
** make sure to use each for the right purpose
* Projectiles
** improve ricochet, gravity related stuff is funky
* target types
** cone
** self-area/multi
* status types
** dispel - should work on individual effects
** silence
** paralysis/stun
* Expose a tonne of constants to Cubescript for configuration at the game maker's discretion. These include leveling and power curves
* arbitrary trigger bounding box scales

=GUI=
* inventory
** item examination
* status effects
* trade
* stats
* crafting
* journal
* newui variants

=Recipes=
* (maybe) allow in game apparatuses to act as a catalyst
** (maybe) several catalysts and ingredients list? or just duplicate and alter the recipe?

=AI=
* queued prioritised actions
** most important done first
** multitasking
* waypoints
** randomness
** state - don't favour waypoints which are in use
* ai tags
** identify purpose and effect of entities in game world for the AI (parsing the script for these is simply not practical)
*** alternatively use simpler more specific types, such as "door", "container", "portal" and "mover" as opposed to a singular "object"

=Cutscenes=
* create a cutscene variant which can't be skippped (maybe)
* some sort of skipping bar (1000 ms?) to prevent accidental skips

=Renderer=
* particles for active spell effects
* render attachments/equipment
* animations for weapons
** generic animations, unarmed strike, melee strike, bow shoot, gun shoot, etc

=Journal=
* quests
* log entries
* sorting and filters

=Sound=
* sounds while charging spells
* sounds for projectile firing, travel and death
* sounds for active statusgroups
* (maybe) voiced dialogue

=I/O=
* flat file export of current script/data definitions (maybe)
** couple with ingame menus for realtime modification (maybe)
* better range checks and protection
* save and restore AI directives

=Particles=
* set particle effects for entity afflicted status effects
* vary spawned amount of particles depending on distance (few when close, full amount when far away)
* explicit variable for setting waypoint drawing distance

RPG tutorial

2011-10-09T10:37:23Z

Hirato: /* Part 6 */

File:RPG tutorial map2.jpg

2011-10-09T10:36:38Z

Hirato: suggested layout for the second tutorial map

suggested layout for the second tutorial map

RPG tutorial

2011-10-09T10:26:47Z

Hirato: /* Part 6 */

RPG tutorial

2011-10-09T07:10:23Z

Hirato: /* Part 1 */ typos

RPG todo

2011-10-06T09:42:07Z

Hirato:

=Script=
* Timers
** copy reference table
** countdown to 0 before executing.
** update every frame, but execute only outside of cutscenes.

=Gameplay=
* hotkeys
* special item properties
** money (constant value for all purposes)
** cursed status
** unidentified status
*** hide true power or make it a lot less useful?
* (maybe?) character generation
* looting and trading... hardcode references "loot" and "trade"?
* sneaking/stealth
** light and visibility
** silhouettes and light levels?
** stealing
* proper friendly fire protection
** 0 - no protection (default)
** 1 - prevents you from hurting yourself
** 2 - 1 + prevents you from hurting allies
** 3 - allows injury to hostile characters only
* spell types
** movement (paralysis counters)
** vocal (silence counters)

=Logic=
* the consume use case for books and potions.
* statusgroups on items
** temporary spells that alters the properties of the weapon
** multiple at once with different targets.
* temporary spell effects for wielded items,
** multiple status effects on a single use, separate chargeflags, multiplier, duration and element.
** make sure to use each for the right purpose
* Projectiles
** improve ricochet, gravity related stuff is funky
* target types
** cone
** self-area/multi
* status types
** dispel - should work on individual effects
** silence
** paralysis/stun
* Expose a tonne of constants to Cubescript for configuration at the game maker's discretion. These include leveling and power curves

=GUI=
* inventory
** item examination
* status effects
* trade
* stats
* crafting
* journal
* newui variants

=Recipes=
* (maybe) allow in game apparatuses to act as a catalyst
** (maybe) several catalysts and ingredients list? or just duplicate and alter the recipe?

=AI=
* queued prioritised actions
** most important done first
** multitasking
* waypoints
** randomness
** state - don't favour waypoints which are in use
* ai tags
** identify purpose and effect of entities in game world for the AI (parsing the script for these is simply not practical)
*** alternatively use simpler more specific types, such as "door", "container", "portal" and "mover" as opposed to a singular "object"

=Cutscenes=
* create a cutscene variant which can't be skippped (maybe)
* some sort of skipping bar (1000 ms?) to prevent accidental skips

=Renderer=
* particles for active spell effects
* render attachments/equipment
* animations for weapons
** generic animations, unarmed strike, melee strike, bow shoot, gun shoot, etc

=Journal=
* quests
* log entries
* sorting and filters

=Sound=
* sounds while charging spells
* sounds for projectile firing, travel and death
* sounds for active statusgroups
* (maybe) voiced dialogue

=I/O=
* flat file export of current script/data definitions (maybe)
** couple with ingame menus for realtime modification (maybe)
* better range checks and protection
* save and restore AI directives

=Particles=
* set particle effects for entity afflicted status effects
* vary spawned amount of particles depending on distance (few when close, full amount when far away)
* explicit variable for setting waypoint drawing distance