Copyright: Furcadia DragonSpeak Help v 0.3
Citation: -- Furcadia DragonSpeak Help --


Introduction

Let me just start out by explaining what DragonSpeak is and how it fits in with everything else.  DragonSpeak is a simple way that anybody can add special effects to the maps they make.  You can make things appear and dissappear, make tricks and puzzles, play cool sound effects, and lots more.  You don't have to be a programmer or a genius to do it either.  If you follow these instructions you'll be making neat things happen in just a few minutes.

Basically, each map that you create can have a sort of "script" to control what kinds of special things happen there.

DragonSpeak scripts are based on a series of "causes" and "effects". When you put a cause and an effect together, you've made what we call a "trigger".  You can have as many different triggers as you want, it just depends how many things you want to have happening on your map.  You should probably start out with just a few simple things to get the hang of it, then you can put in as many as you like.


Simple cause - effect example

The way you actually make triggers is by double clicking the lines you want from the text on the right in your editor.  That will copy it to where the cursor is in your script file (on the left).  Then all you have to do is fill in the spots where there's a "#" with an actual number.  If you want to use the same line multiple times or move or copy a large amount of script, you can do this by selecting "Cut" or "Copy" from the Edit menu and using "Paste" to place it.

The simplest kind of trigger has just one "cause" and one "effect". The causes are the lines on the right under the "Causes" tab.  Effects are probably off your screen to the right.  So use the arrows in the upper right corner of the window to scroll back and forth through the tabs.  Let's try a quick example.  Find and double click these two lines, one cause and one effect:

Whenever somebody moves,

      and

play sound # to whoever set off the trigger.

Now move the cursor to the "#" after the word "sound" (in the left window).  Delete the "#" and replace it with "32".  It should look like this:

(0:1) Whenever somebody moves,

(5:8) play sound 32 to whoever set off the trigger.

Go to the File menu and select "Save". Start Furcadia and upload your dream to test it.  Move with the arrow keys, and you should hear a sound effect every time you take a step.

Congratulations, you just made your first DragonSpeak script.  That's

all there is to it.

You can try playing around with different sounds if you like.  Change

the "32" to "66" and see what that sounds like.  Try other numbers from

1 to 88..


Multiple effects, areas and filters
Multiple effect, areas and filters

What else can you do with DragonSpeak?  Maybe you've already looked at some of the other causes and effects and thought about what they do.  You can tell just by reading them a lot of times, especially if you've already been drawing maps and are familiar with floors and objects and things. If you want to, you can even just try some of the effects out and see what they do on your own.  This isn't like monkeying with the controls of a nuclear reactor.  DragonSpeak was designed so that nothing you do can possibly hurt your computer, even if you make a mistake.  The worst that should happen is that it won't do exactly what you want, or maybe won't do anything at all.  You don't have to worry about ruining the nice map you drew either, because even if DragonSpeak changes things they will return to normal when you reload the map.

The tricky part of figuring out most of the causes and effects is figuring out which numbers to use. The best way to do this is to use the editor to find them.  Let's say for instance the cause

    (0:2) When somebody moves into floor type #,

caught your eye, and you wanted to use it to make a special magic carpet square that plays a sound effect whenever anyone steps on it. You need to find out what the right number is for your carpet, to replace the "#" with.  Go into the editor and press 2 to go into Floor mode. If your carpet is already on the map, you can move the cursor over it and use <g> to show you the right number (box on the left with the picture of the object or tile).  If you haven't put it down yet, you can change the cursor to the shape you want, then look at the number of it to see whichto use for it.  Be sure to put that floor on the map somewhere so you can step on it and try it out.

Let's say you picked the carpet shape that's floor number 146.  It's very colorful!  Now you could do:

(0:2) When somebody moves into floor type 146,

(5:8) play sound 45 to whoever set off the trigger.

Congratulations, you've just made a mysterious purring rug!

You can also use the editor to check out the numbers of objects.  Do it the same way you checked floors, but press "1" to go into object mode. If you want to use a line that needs you to fill in a position, like

    (0:7) When somebody moves into position (#,#),

You can move to the spot you want in the map editor and read the "x=" and "y="  parts to find the two numbers to use (lower left box).

Let's try an example with objects.  We'll also learn a new trick - instead of just one effect, you can put two or more.  Once the cause happens, DragonSpeak will set off every effect it sees up until the next cause in the list.  Here's an example with two:

(0:7) When somebody moves into position (20,10),

(5:4) place object type 31.

(5:8) play sound 32 to whoever set off the trigger.

Did you find the right place to walk to test that?  Wow, it put stuff all over the whole map, didn't it?  That's why you might want to learn how to use "areas" and "filters".  You can put them between your cause and your effects to limit the places where things happen.  So instead of cause-effect, you can use cause-area-effect, or cause-filter-effect, or even cause-area-filter-effect.

Areas just specify a place for things to happen.  If you don't use one, they will happen all over the whole map, as you found out.  All of the lines beginning with 3 are areas.  Try adding one to the example above, so it looks like this:

(0:7) When somebody moves into position (20,10),

(3:4) within the rectangle (18,12) - (24,15),

                       (upper left - lower right)

(5:4) place object type 31.

(5:8) play sound 32 to whoever set off the trigger.

That's a much more reasonable number of pillows, isn't it?

The lines beginning with 4 are filters.  They can be used to limit the effects to only happening in some parts of the area you pick, instead of all of it.  For example, place a couple of chairs (object 04) where the pillows appeared in the previous example, then try this script:

(0:7) When somebody moves into position (20,10),

(3:4) within the rectangle (18,12) - (24,15),

                       (upper left - lower right)

(4:8) only where there are no objects,

(5:4) place object type 31.

(5:8) play sound 32 to whoever set off the trigger.

See?  The 4:8 filter only allowed the pillows to be placed where there wasn't already an object.

You can combine more than one filter if you want to.  Then the effect will only happen in places where ALL of the filter conditions are true.


How it works and its limitations (the rules)

Currently you can have a maximum of 1500 lines in one DragonSpeak script.  Blank lines or comments don't count, only the template lines.

Each trigger *must* begin with a "cause", one of the templates that begins with "(0:".  There can only be one cause per trigger, the next cause found is assumed to be the beginning of a new trigger.

After the cause, you can have some of the "additional conditions", the ones with "(1:".  If you want to have any of these at all, they must go right after the cause line.  You can have none, one, or several additional conditions.  What they do is that when the cause happens, all of the additional conditions (if any) are checked right away.  If ALL of them are also true, the effect or effects of the trigger will be set off.  But if there's even one additional condition that's not true, then nothing happens.  That's why they all say "and" in them.  This AND that AND that other thing must all be true for the trigger to do anything.

Finally, after the cause and additional conditions, you can have as many areas (3), filters (4) and effects (5) as you want.  You should have at least one effect in there somewhere or the trigger won't do anything.

Only one area can be in effect at once.  If you don't specify one the default is "everywhere on the map".  If you want to have several effects go off at different places, you can just put a different area before each one.  The perevious active area always gets replaced with the newly specified one when you put a new area line.  You can put two areas commands in a row if you want, but it would be fairly pointless, as the second one would override the first one immediately, so the first one would have no impact on the results at all.

Filters, unlike areas, are cumulative.  Think of it like each filter is a clear sheet of plastic with some blacked out sections covering up parts of the area they're laid on top of.  Now imagine laying two or three of those sheets on top of each other.  The places within the area where the effect will happen are only the ones that none of the filters happens to "filter out".  Or to look at it another way, they are the places where all of the filter conditions are simultaneously true.  Since the filters always add more conditions until the start of the next trigger, there's the "clear all filters" command to let you start from scratch on the next effect with no filters in place until you add some more again.  The default filtering, if no filter lines are included in a trigger, is to do no filtering and apply the effect(s) to everyplace in the area given (or everywhere on the map if you have no area and no filter).

Effects do stuff, and they do it in the sequence listed.  Note that the game screen isn't redrawn every time a shape changes, or even every time an effect line goes off.  In the original game, after  every TRIGGER, the screen was updated.  You can go back to this mode with the "turn on classic mode" effect.  Mostly people will only want that if they have old maps they made with the earlier versions of Furcadia, and want them to keep working the way they did before. Now when something sets off one or more triggers, like a furre moving, a second of time passing, someone getting or using an item, the game will set off ALL the effects, and only update the screen at the very end.  This lets you change several things at once, visually. Alternately, if you want people on your map to see one thing happen first and then see the next thing happen immediately after, you can use the "redraw the screen" effect at various places in your sequence of effects.

Note that some effects don't have anything to do with the areas and filters.  The play sound effects ones only go off once, and ignore the area and filter conditions.  Also, the first two "move the furre to" lines don't work with the areas and filters, they only affect the furre that set off the trigger.  The next two "move" effects do work with the areas and filters.  Only these two will work with the (0:0) startup causes and (0:100) timer causes - the "move the triggering furre" will do nothing with a timer because timers aren't set off by anybody.  (Father Time notwithstanding.)


Causes

(0:0) When everything is starting up,

    This cause will go off right after you upload your map, and

    then never again.  Not terribly useful.  In the editor it

    goes off right when you enter walkaround mode.

(0:1) Whenever somebody moves,

    This goes off every time somebody takes a single step on the map.

    Turning in place doesn't count, they have to actually walk.  If

    they bump into a wall and don't really go anywhere, the trigger

    still activates.

(0:2) When somebody moves into floor type #,

    This cause is set off when somebody moves if they step into the

    floor type specified, using the same numbering scheme the map

    editor uses for floor numbers.

(0:3) When somebody moves into object type #,

    This cause is set off when somebody moves if they step into a

    spot that contains the object type specified.

(0:7) When somebody moves into position (#,#),

    This goes off if somebody steps into the specific spot with the

    x and y coordinates specified in this cause.

*Special Note*  These three causes go off when a furre TRIES to

    move into a spot with the specified characteristics, even if

    they are blocked by a wall, impassable terrain, or another

    furre and thus don't actually move.  So you can use them to

    make statues that cause things to happen when "bumped into",

    and other effects like that.

(0:9) When a furre arrives in the dream,

    This goes off right when somebody arrives after entering the

    dream portal leading to this map.  It can be used to set the

    entrance to the map by putting a "move the furre to" effect,

    or to inform everyone when a new person arrives by playing a

    sound effect.

(0:10) When a furre leaves the dream,

    This will go off whenever anybody leaves the dream by walking

    into an exit, pressing control-S, quitting the game, or being

    ejected from the dream.

(0:17) When somebody picks up object type #,

    This effect is set off when someone picks up a specific type of

    object off the ground.  Consult the map editor for object numbers.

(0:18) When somebody drops object type #,

    This goes off if the furre is carrying the type of object

    specified in their hands, and drops it.

(0:19) When somebody uses object type #,

    This goes off when someone uses the object type specified, with

    the control-U command.

(0:50) When countdown timer # goes off,

    The game keeps 100 timers that can be set to go off and trigger

    whatever effects you like.  They are numbered from 1 to 100.

    To start with none of them are running, but you can start one

    with the (5:50) start countdown effect.  If you start timer 5

    with a time of 30 seconds, then 30 seconds later any and all

    "when countdown timer 5 goes off" triggers will be executed.

    This will only happen once, after it goes off timer 5 will stop

    until you start it again with another (5:50) effect.

(0:100) When # seconds have passed, offset by #,

    This cause will make a trigger that goes off repeatedly.  You

    specify the number of seconds with the first parameter, and it

    will go off every time that many seconds goes by.  Note that you

    should be careful about having too much stuff happening too often,

    because it can slow down people with slower computers like 486s.

    You shouldn't have things happen every one second unless you really

    need to, and if you do you should have as few things happening

    that often as possible - preferably just one if you need any at

    all.  Every two seconds or every five seconds is better.  Also

    be aware that because of unpredictable delays on the internet,

    time intervals might not go by with perfect regularity for all

    furres visiting your map.  The offset parameter is meant for

    desynchronizing events when you have more than one trigger using

    timed events with the same time interval.  If you only have one

    tend second trigger, it doesn't matter what the offset is and

    you might as well use zero.  If you have two different ten second

    triggers (or any other matching interval), they will go off at

    the same time every time if they have the same offset, and at

    different times if they have different offsets.  Ten seconds

    offset by zero would go off at :00, :10, :20, :30 etc.  Ten

    seconds offset by five would go off at :05, :15, :25, and so on.


Conditions
Additional conditions

(1:2) and they move into floor type #,

(1:3) and they move into object type #,

(1:7) and they move into position (#,#),

    These match three of the CAUSE types.  They're here to let you

    make a cause that requires two or more of those conditions to

    be true.  Note that when they're used with a CAUSE that doesn't

    actually involve moving, like when a furre picks up or uses an

    object for instance, they will work if the condition matches the

    spot they're standing at.  If they did move but were blocked

    from actually entering the destination spot, that spot is still

    the one that's checked, not the one they remain in.

(1:17) and they (moved from/are standing at) floor type #,

(1:18) and they (moved from/are standing at) object type #,

(1:19) and they (moved from/are standing at) position (#,#),

    These are similar to the last three, only they check the spot

    that the furre moved OUT of, rather than the one they moved into.

    And also, if they didn't really move the trigger will check where

    they are standing still at when the CAUSE happens.

(1:102) and they didn't move into floor type #,

(1:103) and they didn't move into object type #,

(1:107) and they didn't move into position (#,#),

(1:117) and they (didn't move from/aren't standing at) floor type #,

(1:118) and they (didn't move from/aren't standing at) object type #,

(1:119) and they (didn't move from/aren't standing at) position (#,#),

    These are the same as the previous six, except that they let

    things happen when their conditions do NOT match the floor,

    object, or position numbers of the player, rather than when

    things DO match.  For instance, "didn't move into floor type 20"

    would work with any floor type except for 20.

(1:1000) and a random dice roll comes up (# percent of the time),

    This if for making things that happen only some of the time.

    A totally random determination is made, the percentage should

    range from 1 to 99.  (You could use 0 or 100 but that would be

    pretty pointless!)  If you use 50, then the effect will go off

    half of the times the trigger's CAUSE is triggered, and do nothing

    the other half.

(1:1002) and they are holding item # in their paws,

(1:1004) and they're not holding item # in paws,

    Checks for what the furre is carrying, you can require them to

    have a specific item, or require them NOT to have one.  Note that

    zero means "carrying nothing".  And "not holding item 0" would

    mean "carrying anything at all".

(1:1011) and position (#,#) is floor type #,

(1:1012) and position (#,#) is not floor type #,

(1:1013) and position (#,#) is object type #,

(1:1014) and position (#,#) is not object type #,

    These four let you check specific spots on the map for certain

    conditions.  You can use this to check whether some previous

    thing has happened to decide whether to do anything by looking

    at the results it produces on the maps.  Or you can set up a

    spot that the furre can't get close enough to see, and use it

    as a "flag variable", having some triggers set it to certain

    values, and other triggers check it to decide whether to go off

    or not.


Areas

(3:1) everywhere on the whole map,

    Makes the following effects happen in every single spot on

    the map.  (Unless some filters are in effect).

(3:2) at position (#,#) on the map,

    Makes effects happen only in one specific spot on the map.

(3:4) within the rectangle (#,#) - (#,#),

                                   (upper left - lower right)

    Makes effects happen at every spot within the specified

    rectangle, (except those that are filtered out).

(3:5) where the triggering furre (moved from/is standing at),

    Makes effects happen in the single spot that the furre who

    set off the trigger came from, or where they are now if

    they are standing still.

(3:6) where the triggering furre moved into,

    Makes effects happen in the spot the furre moved into, or

    the spot they tried to move into if it was blocked.


Filters

(4:0) clear all filtering,

    Cancels any filters currently in effect.

(4:1) only where the floor is type #,

    "Filters out" spots where the floor doesn't match the

    specified type, and keeps following effects from happening there.

(4:2) only where the floor is not type #,

    "Filters out" spots where the floor doesn match the specified

    type, and keeps following effects from happening there.

(4:3) only where an object type # is,

    Filters out spots that don't have the specified object.

(4:4) only where there is no object type #,

    Filters out spots that do have the specified object.

(4:7) only where there is an object,

    Filters out spots with no objects.

(4:8) only where there are no objects,

    Filters out spots that do have an object.

(4:9) only in places where someone can walk,

    Filters out places that furres can't step into.

(4:10) only in places that can't be walked into,

    Filters out places that furres can step into.


Effects

(5:1) set the floor to type #.

    Changes the ground from whatever it was to the new specified type,

    everywhere within the specified area that matches all the filter

    conditions.

(5:2) change floor type # to type #.

    Changes the floor in each affected spot to the second type only

    if it matches the first type, otherwise leave it alone.

(5:3) swap floor types # and #.

    If the floor in an affected spot is one of the two types listed,

    it will be changed to the other.  All spots of any floor type

    other than those two will be left alone.  Good for toggle effects.

(5:4) place object type #.

(use zero to clear out objects)

    Places an object on the map in each affected spot, replacing any

    existing one that may have already been there.  Zero represents

    "no object" so it can be used to wipe out objects you want to get

    rid of.

(5:5) change object type # to type #.

    If the object in an affected spot matches the first value, it is

    replaced with one of the second value, otherwise nothing is done.

(5:6) swap object types # and #.

    In each affected spot, if the object is either of the two listed

    types, it is changed to the other one.  This is commonly used for

    things like levers that toggle between two positions.

(5:8) play sound # to whoever set off the trigger.

    Plays a sound effect only to the furre that activated the trigger.

    If it was a timer trigger or something like that it won't play

    the sound to anybody.  The list of sound effect numbers is at the

    end of this file.

(5:12) play sound # to everyone on the map.

    Plays a sound to everybody.

(5:14) move the triggering furre to (#,#) if there's nobody already there.

    This effect moves a furre instantly to another spot on the

    map.  You can use it to make teleporters, or you can make stairs

    doors, boats, etc. that move you to a different part of your map.

    This move command will only move to the exact spot mentioned, if

    that spot is occupied it simply won't move the furre at all.

(5:15) move the triggering furre to (#,#), or to someplace nearby if it's occupied.

    This is like the previous command, except that if there is

    someone already in the spot specified, it will move the furre to

    someplace close by.

(5:16) move any furre here to (#,#) if there's nobody already there.

    This effect can be used to move furres other than the one who

    set off the trigger.   You should use it whenever you want to

    teleport people with timer effects (which are triggered by

    nobody specific), if you want to have more than one furre moved

    all at the same time, or if you want to have one furre do

    something like pulling a lever, and have it move some OTHER

    person when they do that.

(5:17) move any furre here to (#,#), or to someplace nearby if it's occupied.

    This is like the previous command, except that if there is

    someone already in the spot specified, it will move the furre to

    someplace close by.

(5:21) move the object to (#,#).

    This moves any object that's in the affected spot to the new

    location, removing it from the old one.  Note that if there is

    no object in the source location, then "object 0" will be moved

    to the new spot, erasing whatever was there.  Also, this effect

    was intended for use with area/filter setups that will only

    specify one spot on the map.  If you have an area with more

    than one spot in it, it will move them all one at a time,

    each one wiping out the last object that was placed there, so

    that all of the source spots are empty, and the destination

    spot contains only what was in the last spot moved.

(5:22) copy the object to (#,#).

    This is like the move command, only it places an extra copy of

    the object at the destination spot specified without changing

    what was in the original location.  Copying an empty spot will

    clear out whatever object might have been in the destination

    location.

(5:23) swap the object with the object at (#,#).

    This exchanges the contents of the affected spot with whatever is

    at the location specified.

(5:24) copy the floor to (#,#).

    This copies the floor terrain at the affected spot to the

    floor at the specified location.

(5:25) swap the floor with the floor at (#,#).

    This exchanges the floor at the affected spot with the specified

    location's floor.

(5:50) set countdown timer # to go off in # seconds.

    This works in conjunction with the (0:50) countdown timer cause.

    It lets you set up an event to happen later, rather than right

    away the moment the trigger goes off.  You can use numbers from

    1 to 100 to specify which timer to use.  That way you can have

    several different timers counting down at once!  You specify

    how many seconds each one will count down from with the second

    parameter.  When it reaches zero, any (0:50) causes that have

    that timer indicated will go off.

(5:100) turn on "classic" mode and update the screen after each trigger.

    This is mainly just for people that used versions of Furcadia from

    1.0 through 1.53, and want their old scripts to keep working the

    way they used to.  If you're writing new scripts you shouldn't

    need this for anything, as the new (5:1000) redraw effect gives

    you total control over when updates happen.

(5:101) turn "classic" mode back off.

    This will cancel the effects of any (5:100) classic mode effect

    that has gone off earlier.

(5:1000) redraw the screen and show everything that's just changed.

    Normally when a lot of effects go off at once, the players will

    see the screen change instantly to show what things look like as

    the end result of everything that happened, like it happened all

    at once.  If you want to show some of the intermediate stages, to

    do animation or for other reasons, you can put this effect in at

    one or more spots in your sequence of effects.  It will show all

    the changes that have happened so far at the point in time where

    this effect happens.


Sound effect list
Sound effect list:

1=pop1	23=click4	45=purr1	67=bird4

2=pop2	24=click5	46=purr2	68=bird5

3=open	25=click6	47=purr3	69=bird6

4=close	26=click7	48=drum1	70=crow

5=flutter	27=click8	49=drum2	71=loon

6=windup	28=quiet click	50=drum3	72=frog

7=rattle	29=strange1	51=drum4	73=horse

8=bird1	30=strange2	52=drum5	74=drip2

9=bird2	31=strange3	53=drum6	75=clonk

10=bird3	32=drip	54=drum7	76=chimes2

11=cheep	33=drop	55=clink	77=drum8

12=quaver	34=plip	56=clank	78=rimshot

13=bell1	35=water	57=violin	79=fanfare2

14=bell2	36=splash	58=kalimba	80=sproing

15=cricket	37=big splash	59=flute

16=ostrix1	38=plop	60=lute

17=ostrix2	39=boing	61=harp

18=ostrix3	40=splat	62=tada

19=ostrix4	41=floomp	63=harpsichord

20=click1	42=shut1	64=trumpet fanfare

21=click2	43=shut2	65=chimes

22=click3	44=sliding stone	66=cuckoo clock