DragonSpeak Reference

This page contains a technical summary of exactly how the different DS lines work, as well as how the DragonSpeak engine works!

Table of Contents

DragonSpeak Categories

This is a table for you to reference in case you don't remember what a type of DS line will do. There are 5 categories in total:

Causes:

(0:#)

The cause lines show what causes any DS effect, from walking or turning to speaking or emoting a command.

Additional Conditions:

(1:#)

These narrow down when the causes can take effect. (Only when a player is a certain species, a particular name, etc. can this begin.)

Areas:

(3:#)

These limit where the DS can take effect. Certain positions, certain areas etc.

Filters:

(4:#)

These further limit the areas to positions with particular floors or Items etc. They stack up.

Effects:

(5:#)

The effects are the things that happen when the causes and additional conditions are met. You can stack lots of effects on to the end if you want lots of things to happen due to one cause.

Extra Comments:

*

To add a comment to your DS file, simply type your comment with an asterisk * at the start of the line. The text will turn blue, indicating it's a comment!

DragonSpeak Structure Notes

Parser

First a couple of notes about the structure of DragonSpeak scripts. The parser in the game actually scans the file and only reads the characters 0 1 2 3 4 5 6 7 8 and 9. Anything that isn't one of those is ignored, unless the DS line calls for a parameter, such as a string (text).

Comments

You can put comments anywhere in the file you want to explain what you're doing as long as you start the line with an asterisk *.

Rewording

You can also modify the text in the template DS lines - they are only worded the way they are to help you understand your own scripts, they don't have to keep the same wording. There are two different files that contain the basic DS template.

Default text to keep

Each DS file must start with a line that looks like DSPK V04.00 Furcadia and end with the line *Endtriggers* 8888 *Endtriggers*. These lines are automatically populated and are highlighted in green. You should avoid modifying either of these two lines or your DS file may not function afterwards. Everything in between these lines is automatically run start to finish for each trigger.

DS line limit

Free dreams can have a maximum of 8,000 lines of DragonSpeak. Blank lines and comments don't count towards this limit. You can extend this limit to a maximum of 20,000 lines by purchasing a group package.

You can find out how many lines are in your script by going to Tools > Real Lines of DS in the DragonSpeak Constructor. The number of lines are also displayed when you enter a Dream.

How to structure DS lines

Each trigger must begin with a cause, which is one of the DS lines that begins with (0:#)

After any cause, you can optionally 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 - they will not work after areas, filters, or effects. You can have none, one, or several additional conditions.

What additional conditions 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 usually if there's even one additional condition that's not true, then nothing happens. That's why they all say the word and in them. This AND that AND that other thing must all be true for the trigger to do anything.

Here's an example: 

(0:4) When someone turns,

     (1:36) and they are male,

     (1:29) and they are a Squirrel,

           (5:200) emit message {Show me your nuts!} to the triggering furre.

So this message will only happen if the person who turns is male and is a squirrel.

Here's an example that will not work:

(0:4) When someone turns,

     (1:36) and they are male,

     (1:29) and they are a Squirrel,

     (1:20) and they are a Rodent,

           (5:200) emit message {Show me the goods!} to the triggering furre.

Why won't this work? In Furcadia you can only be 1 species at a time, and therefore this trigger wouldn't do anything.. in other words, it would be pointless because it would never occur. So, be careful when using additional conditions that you don't make impossible scenarios!

You can also stack several causes together if you follow them with effects. This means "if this cause OR this cause OR this cause happens, then do this." You can also stack causes with additional conditions, such as "When this happens, and this, when this happens, and this, have this effect" and it will work like this: "When this happens, and this, OR when this happens, and this, have this effect."

Here's an example:

(0:12) When someone sits down,

      (1:18) and the triggering furre (moved from/is standing at) item 1,

(0:13) When someone lays down,

      (1:18) and the triggering furre (moved from/is standing at) item 2,

(0:12) When someone sits down,

      (1:18) and the triggering furre (moved from/is standing at) item 3,

            (5:200) emit message {You're on a pillow.} to the triggering furre.

This reads as: When someone sits down and they are on pillow 1, OR when someone lays down and they are on pillow 2, OR when someone sits down and they are on pillow 3, tell them they are on a pillow.

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, or it will do other unexpected things. For instance, let's say you wrote a cause without an effect. Then you start another trigger. Since you didn't add an effect to the previous cause, it will behave as an OR (mentioned above).

Here's an example: 

(0:1) Whenever someone moves,

     (1:5) and they successfully moved,

*someone forgot to add stuff here*

*This next trigger seems like it would have nothing to do with the previous one, but since the previous DS lines do not have an effect, the message "Boop!" will appear every time someone moves to a new tile, OR when they turn.*

(0:4) When someone turns,

     (5:200) emit message {Boop!} to the triggering furre.

Area rules

Only one area can be in effect at once. If you don't specify an area, 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 previous 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.

Filter rules

Filters, unlike areas, are cumulative. Think of each filter as 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, with different blacked out patterns, on top of each other. Only the places where there are no blacked out spots is where the effect will happen.

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

Filters, areas, and effects could be appended to the end of a block of DS in any order, but the end line in a block must be an effect otherwise the script may not behave as intended. An example of cycling those line types;

(0:31) When someone says {Spawn flames},

      (4:1) only where the floor is 0, (Default grass)

      (4:40) only where the effect overlay is 0, (No effect)

      (3:50) 1 step(s) northeast (up and right) from where the triggering furre (moved from/is standing),

            (5:150) place overlay effect 50. (Wildfire effect)

            (5:1) set the floor to 211. (Orange Disco floor)

      (3:51) 1 step(s) southeast (down and right) from where the triggering furre (moved from/is standing),

            (5:150) place overlay effect 50. (Wildfire effect)

            (5:1) set the floor to 211. (Orange Disco floor)

      (3:52) 1 step(s) southwest (down and left) from where the triggering furre (moved from/is standing),

            (5:150) place overlay effect 50. (Wildfire effect)

            (5:1) set the floor to 211. (Orange Disco floor)

      (3:53) 1 step(s) northwest (up and left) from where the triggering furre (moved from/is standing),

            (5:150) place overlay effect 50. (Wildfire effect)

            (5:1) set the floor to 211. (Orange Disco floor)

      (4:0) clear all filtering,

      (3:8) everyplace the triggering furre can see,

      (4:40) only where the effect overlay is 50, (Wildfire effect)

      (4:1) only where the floor is 211, (Orange Disco floor)

           (5:75) make any furre present lie down.

The above script first applies two filters after a command, stacks multiple areas and effect lines, clear the filters, applies a new area (otherwise it’d execute only 1 step North-west of the player), applies new filters (if we didn’t clear the filter, and apply new ones, the script will still look for floor 0 and effect 0), then make any player preset lay down within those parameters. This script is needlessly bulky just to demonstrate the cycling.

Effect rules

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. When something sets off one or more triggers, like a player 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 this particular line sometimes generates lag.

Also note that some effects don't have anything to do with the areas and filters. For instance, the play sound effect to everyone on the map effect ignores the area and filter conditions. Another thing to note is that anything with the triggering furre in it would ignore areas and filters.

Timed based events such as When countdown timer # goes off wouldn't do anything with lines that have the triggering furre, unless you used a line to make someone specifically targeted become the triggering player. Anything with any furre present would affect everyone on the map, or if given areas and filters, would affect a group of people in those places.

DragonSpeak Lines Explanation

Here's a short summary of many of the DragonSpeak commands. If you use DragonSpeak Constructor, you can find additional line explanations on the DS Help tab in the sidebar DS manager. Note that there are many more lines than what's listed here, but this should be a handy reference!

Causes

(0:0) When everything is starting up,

This cause will go off right after you upload your map, and then never again. Useful for setting up silent speech prefixes, regions, variables, etc. Does not work for setting PhoenixSpeak values.

(0:1) Whenever someone 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.


Note: This command generates lag if you don't use enough additional conditions or filters.

(0:2) When someone moves into floor #,

This cause is set off when someone moves if they step into the floor type specified, using the same numbering scheme the map editor uses for floor numbers.

(0:3) When someone moves into item #,

This cause is set off when someone moves if they step into a spot that contains the item type specified.

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

This goes off if someone steps into the specific spot with the x and y coordinates specified in this cause.


Note: This one and the previous three causes go off when a player tries to move into a spot with the specified characteristics, even if they are blocked by a wall, impassable terrain, or another player 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 someone 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 someone leaves the dream,

This will go off whenever anyone leaves the dream by walking into an exit, pressing control-S or control-B, quitting the game, or being ejected from the dream.

(0:17) When someone picks up item #,

This effect is set off when someone picks up a specific type of item off the ground with the control-G (F2) command. Consult the map editor for item numbers.

(0:18) When someone drops item #,

This goes off if the player is carrying the type of item specified in their hands, and drops it with the control-G (F2) command.

(0:19) When someone uses item #,

This goes off when someone uses the item type specified, with the control-U (F3) 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. You can number them from 1 to 100.


*The system can technically track up to 1000 timers at a time, however due to inconsistencies, going over 100 isn’t recommended.


To start with, no timers 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. 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 players 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 ten 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.

Additional Conditions

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


(1:3) and they move into item #,


(1:4) and they bump into a furre,


(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 player picks up or uses an item 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 #,


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


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

These are similar to the last three, only they check the spot that the player 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 #,


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


(1:104) and they didn't bump into a furre,


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


(1:112) and the triggering furre is not facing towards position (#,#),


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


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


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

These are the same as the previous additional conditions, except that they let things happen when their conditions do not match the floor, item, 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 is 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 player is carrying. You can require them to have a specific item, or require them NOT to have one. Note that 0 means carrying nothing. And not holding item 0 would mean carrying anything at all.

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


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


(1:1013) and position (#,#) is item #,


(1:1014) and position (#,#) is not item #,

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 player 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). This is the default behavior for areas, meaning it’ll be applied anyway unless another area line is present.

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

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

(3:3) within the diamond (#,#) - (#,#),

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

Makes effects happen at every spot within the specified rectangle, or diamond (except those that are filtered out). In Furcadia’s perspective, diamonds are shaped like a rhombus, with smooth edges. Rectangles are the ones with the jagged edges reminiscent of the highlight tool in the map editor.

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

Makes effects happen in the single spot that the player 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 player 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 #,

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 #,

Filters out spots where the floor do match the specified type, and keeps following effects from happening there.

(4:3) only where an item # is,

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

(4:4) only where there is no item #,

Filters out spots that do have the specified item.

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

Filters out spots with no items.

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

Filters out spots that do have an item.

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

Filters out places that players can step into.

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

Filters out places that players can’t step into.

Effects

(5:1) set the floor to #.

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 # to floor #.

Changes the floor in each affected spot to the second type only if it matches the first type, otherwise it'll 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 item #. (use 0 to clear out items)

Places an item on the map in each affected spot, replacing any existing one that may have already been there. Item 0 represents no item so it can be used to wipe out items you want to get rid of.

(5:5) change item # to #.

If the item in an affected spot matches the first value, it is replaced with one of the second value, otherwise nothing is done.

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

In each affected spot, if the item 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.


(5:9) play sound # to any furre present.

These two lines play a sound effect. (5:8) plays only to the person that activated the trigger. So, if it was a timer trigger or something similar, that line won't play the sound to anybody. If you're using a timer, instead use (5:9) after setting an area.

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

This effect moves a player 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 or unwalkable it simply won't move the person at all.

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

This is like the previous line, except that if there is someone already in the spot specified, it will move the player to someplace close by.

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

This effect can be used to move players 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 person moved all at the same time, or if you want to have one person do something like pulling a lever, and have it move some OTHER person when they do that. Needs to be combined with areas or filters, otherwise it’d try to move everyone on the map.

(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 person to someplace close by.

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

This moves any item that's in the affected spot to the new location, removing it from the old one.


Note that if there is no item in the source location, then item 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 item 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 item to (#,#).

This is like the move command, only it places an extra copy of the item at the destination spot specified without changing what was in the original location. Copying an empty spot will clear out whatever item might have been in the destination location.

(5:23) swap the item with the 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 1000* 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.


*1000 timers are supported, however they may not behave as intended using the default (0:50) line to detect them. The do work however with (0:49) When any countdown timer goes off. Combine this with (5:327) set variable # to the number of the countdown timer that just went off, and then use a separate block with (0:49) and (1:200) to use them properly.

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



DragonSpeak is a wonderful way to add magic and life to your Dreams, so feel free to explore and try new things with your own ideas. If you have any further questions about it, feel free to contact the Beekins in game by saying help I need help with my dream!

Account E-Mail

Password