More technical specs and tips

DragonSpeak is an easy to learn plug-and-play scripting language that is great for beginners, but it can also help build a logical programming mindset. DS most closely resembles assembly or procedural languages, which means changes at the top of your DS file can impact the outcome of triggers near the bottom (i.e the entire DS file will execute every time).

One potentially helpful analogy (if you're into math, anyway) may be to imagine that your DS file is one large math statement, where each trigger is a logical if statement. The cause, condition, area and filter lines combine to form this statement, and if the statement is true, the effect lines will trigger. Since effect lines near the top of your DS can impact if statements near the bottom, order matters!

Every time something happens, a request to run your DS file is queued. These requests run synchronously and in order. Another helpful metaphor is to imagine your DS file is an ice cream truck and each queued request is a customer standing in line. Everyone waits for their turn, because the ice cream vendor will only serve one customer at a time in the order that they arrived. The vendor does this so that orders, change, and small talk get to the correct customer. In the same way, an event running your DS file is not interrupted or polluted by other events, it will finish the entire file before another event runs.

There is, however, a state to your DS file. Changes to variables, strings, and PS persist from one execution of the file to the next. Consider the ice cream truck example again. Every time a customer interacts with the vendor, they are changing the current state. Perhaps by the time a customer gets to the front of the line, there are no more ice cream tacos, or the vendor doesn’t have change for a large bill. The vendor will still interact with the customer, but they may not be able to fulfill their request as expected.

Best practices

Since DragonSpeak is a type of scripting language, best practices are guidelines intended to help keep your triggers clean and maintainable. This is particularly useful when working on DS with a team, especially if everyone has a different style. Here are some of our suggestions for writing clean DS:

  • Use the DS Constructor's Sections feature to organize and separate specific functions or events in a complex Dream, making it easier to find what you're looking for and remember all the aspects you have already added to your Dream.
    • The right-click, Autocomment feature on each section will also help you for debugging, when you need to isolate parts of your DS file for testing purposes.
  • Follow a naming convention when making variables and strings to avoid typos
    • Use consistent capitalization, whether it be all lower, all upper, or camelcase
    • Use compound words to express meaning, such as starting with a verb like is or has where it makes sense
      • %hasKey vs. %key
    • Establish guidelines for underscores and numbers -- should they be used?
      • %hasKey vs. %has_Key
      • %room as an array vs. %room1
  • Use comments above blocks and in between lines to clarify complex logic. You’ll be surprised how often you forget why you did something!
  • Use caution when removing or changing the descriptive text (non-keywords) in DS lines. Mismatches between descriptive text and line numbers can be extremely difficult to debug and even advanced weavers use descriptive text to quickly understand various triggers!
  • Make backups of your work! Nothing is more frustrating than having hours, days, or even weeks of work lost due to a computer crash or accidental overwrite.
    • Use a flash drive or external hard drive to save regular backups
    • Store your files on the cloud to preserve versioning

Debugging tips

There will be times you can't figure out why your DS isn't working, and there isn't a Mason around to help you. In these trying times, here are some tips on methods you can try to figure out and isolate the error you're experiencing.

In general, the "ice cream truck" metaphor mentioned above is handy to keep in mind, as everything that happens in your DS affects the overall state of the file. So, what can you try if whatever your first attempt was isn't working?

  • Comment out (the autocomment feature in the DS Constructor) large chunks of your DS and see if the other parts are interfering.
    • If you've used the DS Constructor's Section feature to organize your DS, it's easy to then right click each section and then select Autocomment for testing purposes.
  • Move the new DS you're working on to the bottom, middle, or top of the DS file, depending on how it might or might not affect the order of occurrences/events happening in your map.
  • Make a copy of the map and DS and trim off as much extraneous stuff as possible. Sometimes it's the other stuff happening in your map that interferes with your idea.
  • Use the PhoenixSpeak maintenance commands (listed at the bottom of that page) to get a clearer picture of what's happening with your memory management if you're having an issue with any triggers using PS lines.
  • Variables and strings are case-sensitive (A vs a) so double check you don't have any typos in your strings or variables.
    • You can check for mismatched variables by using DS Constructor's Variable information dialog (Alt + V).
  • Try making a second bare bones version of your map with no patches or DS, and only the new feature you're working on is present.
  • Temporarily have any hidden strings, variables, arrays, entry codes, emit their contents out loud in your Dream, line by line as your trigger goes through its event.
    • For example: (5:204) emitloud message {Variable %temp says this now} to everyone on the map.
  • Double check that the lines you copied match the wording of the original line / the line you intended. Sometimes the wrong ones are copied, or the numbers are accidentally mismatched!
    • Remember, the DS parser doesn't care about the wording of the line, only numbers, variables, strings and whatever is inside {these}!
  • Temporarily add debug messages to every effect DS line in your triggers to explain which part of the event is happening and when. For example:

This:

(0:14) When someone picks up any item,
   (3:5) where the triggering player was at,
    (5:4) place item 1.
    (5:22) copy the item to (10,20).
    (5:50) set countdown timer 1 to go off in 10 seconds.

Becomes this (for testing purposes):

(0:14) When someone picks up any item,
   (3:5) where the triggering player was at,
    (5:4) place item 1.
    (5:204) emitloud message {Someone picked up an item and item 1 was placed down.} to everyone on the map.
    (5:22) copy the item to (10,20).
    (5:204) emitloud message {The item was copied to (10,20).} to everyone on the map.
    (5:50) set countdown timer 1 to go off in 10 seconds.
    (5:204) emitloud message {Countdown timer 1 was triggered to go off in 10 seconds.} to everyone on the map.

DreamEd hacks

  • CTRL + Left click to automatically copy coordinates
  • CTRL + M to toggle the Furcadia Field of View when designing large areas
  • Use the Show menu to toggle walls or other layers when designing

DragonSpeak Constructor hacks

  • CTRL + SHIFT + F to bring up the Line Finder
  • CTRL + SPACE for line auto completion
  • Use Sections to break up segments of DS for better manageability
  • ALT + V to bring up the Variable Information dialog -- great for debugging variables!
  • CTRL + R to fix line indentation
  • Listen to default sounds from Tools > Sound Preview without digging through patch folders

Thank you to the Beekin Masons who collaborated and shared their deep knowledge about Dreamweaving to help create these epic tutorials! This amazing collection of tutorials would never have been possible without their help!

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 a mason!

Account E-Mail

Password