Spell Description Language (SDL) Reference Manual

Version: 1.0.1

Purpose: SDL (Spell Description Language) is a procedural extension language for creating, manipulating, and maintaining magical effects in a tabletop RPG or fantasy environment. Each spell script consists of lines (or operators), which together form a dynamic magical effect.

Table of Contents

1. Lexical & Structural Conventions

1.1 Tokens & Keywords

SDL scripts are composed of operators (keywords) and arguments. Operators include words such as create, move, if, then, else, repeat, until, interrupt, bind, and so on. Arguments typically indicate what to create, where to move an effect, and any relevant distances or shapes.

1.2 Case & Whitespace

SDL is case-insensitive in its keywords, but examples typically use lowercase for operators (e.g., create Fire). Whitespace and line breaks separate operators; each new operator generally occupies a new line. Operators such as if...then...else or repeat...until can be written in block form with indentation for clarity, though indentation is not strictly required.

1.3 Comments

Classic SDL does not specify a formal comment syntax. If you adopt a house-ruled version, you might designate lines beginning with # or // as comments. Otherwise, textual commentary is not recognized by the parser.

2. Script & Spell Structure

2.1 Spell Name Declaration

An SDL script must begin with a spell name, followed by a colon (:). This identifier labels the spell for reference in advanced operations (e.g., interrupt).

firewall:
create Fire
...

Syntax:

<spellname>:

where <spellname> is an alphanumeric identifier (e.g., “torch”, “boltbox”, etc.).

2.2 Lines & Operators

Following the spell name, each line contains exactly one operator, plus any arguments. Certain operators (if, repeat) may contain nested operators. The script processes lines in sequence unless altered by flow control operators.

2.3 Execution & Flow

When a script is cast, SDL parses and executes each line from top to bottom. Operators like wait, if, and repeat can alter the sequence or timing of execution.

3. Core Data: Effects & Events

3.1 Effects

An effect is the fundamental magical phenomenon manipulated by SDL. It might be elemental (e.g., Fire, Water) or arcane (e.g., Illusion, Darkness). You typically use create <effect> to initialize it, then manipulate it with other operators (move, scale, etc.).

3.2 Events

Events are conditions or triggers that can suspend or redirect spell flow. Examples: an orc approaching, a phrase spoken, or the script being interrupted. In SDL, events follow a format such as:

<object> <action> <proximity>
<object> "<phrase>" <proximity>

For instance, orc "help" 30' triggers if an orc says “help” within 30 feet.

4. Basic Operators

Basic operators create or directly manipulate an effect. Each operator typically occupies one line.

4.1 create

create <effect> [<name>]

• Description: Initializes a new effect at the caster’s fingertip (point source with no size) unless combined with shape or scale. You may optionally name it.
• Example:

  create Fire myflame
  

  This creates a fire effect labeled "myflame."

4.2 destroy

destroy [<name>]

• Description: Terminates (destroys) a previously created effect. If no name is specified, the most recently created effect is destroyed.
• Example:

  destroy myflame
  

4.3 move

move [<name>] to <distance> pointdir
move [<name>] to lookat <target>
move [<name>] to <x>x <y>y <z>z

• Description: Moves the specified effect to a new location within the caster’s range.
• Examples:

  move myflame to lookat orc
  move myflame to 10' pointdir
  move myflame to 5'x 10'y 15'z
  

4.4 rotate

rotate [<name>] <ang>x <ang>y <ang>z [origin <reference>]

• Description: Rotates an effect around the x, y, z axes, optionally around a specified origin (e.g., lookat orc).
• Example:

  rotate firewall 90y origin lookat orc
  

4.5 scale

scale [<name>] <x>x <y>y <z>z

• Description: Changes the size of an effect (width x height x depth). Default pivot is the effect’s center.
• Example:

  scale myflame 2'x 2'y 2'z
  

4.6 shape

shape [<name>] <pathop1>
              [<pathop2>]
              ...

• Description: Converts an effect into a 2D or 3D shape using path sub-commands (lineto, fill, volume, etc.). When shape is applied, any prior scaling or shaping is overridden by the new form, though position is retained.
• Example:

  shape mywind
    surface 1'thick lookat chest
  

5. Path (Shape) Operators

These operators must be used inside a shape block to define geometry.

5.1 lineto

lineto <thickness>thick <distance> pointdir [smooth]
lineto <thickness>thick lookat <object> [smooth]
lineto <thickness>thick trace

• Description: Draws a line from the current shape position to a new endpoint, with the given thickness.
• Example:

  lineto 2"thick 10' pointdir
  

5.2 fill

fill

• Description: Fills a closed polygon defined by preceding lineto commands in the shape block.

5.3 surface

surface <thickness>thick [lookat] <object>

• Description: Conforms the shape to the outer surface of the specified object, with uniform thickness.

5.4 volume

volume [lookat] <object>

• Description: Fills an object’s entire volume with the effect.

6. Flow Control Operators

6.1 halt

halt

• Description: Immediately stops execution of the current spell script.

6.2 if...then...else

if <eventop1>
   [<eventop2>]
      ...
then
   <operator1>
   [<operator2>]
      ...
[else
   <operator1>
   ...
]

• Description: Conditionally executes a block of operators if any listed event operators evaluate as true. Optionally performs an else block otherwise.
• Example:

  if (orc "charge" 20')
  then create Electricity
  else create Fire
  

6.3 repeat...until

repeat
  <operator1>
  [<operator2>]
  ...
until <eventop1>
      [<eventop2>]
      ...

• Description: Loops the enclosed block until a specified event condition occurs. If multiple conditions are listed, any one of them ends the loop.

6.4 wait

wait <time>
wait until <eventop1>
           [<eventop2>]
           ...

• Description: Pauses execution either for a set duration or until a listed event triggers.
• Example:

  wait 10 sec
  wait until orc "bang" 10'
  

7. Event Operators

SDL can detect real-time events (e.g., creatures speaking, movement within a radius, or interrupted conditions) and respond via conditionals.

7.1 Logical Operators (and, or, not)

These are used to combine event checks. For instance:

(man "help" 10') and (kobold "go" 10')

7.2 interrupted

if interrupted [by <being>]
then ...

Triggers if the current spell has been forcibly changed via interrupt.

7.3 General Event Syntax

<object> <action> <proximity>
<object> "<phrase>" <proximity>

Where object is any creature or effect, action is an observable event (e.g., “move,” “charge,” “attack,” or saying "phrase"), and proximity is a distance or range expression (e.g., “10'”).

8. Special Operators

These advanced commands allow for binding spells to objects, transferring ownership, or dynamically adjusting power and range.

8.1 bind

bind [<spellname>] to touch <object>

• Description: Binds the spell’s reference frame to an object touched by the caster. After binding, references to range or location are relative to that object rather than the caster’s position.

8.2 interrupt

interrupt <spellname> at "<breakpoint>" [revert]
  <operator1>
  [<operator2>]
  ...

• Description: Allows a caster to modify an active or running spell at a specific line (the breakpoint). The new lines replace or append to the original code at that point.
• revert indicates the changes only apply once if inside a loop. Otherwise, changes are permanent (for as long as the spell lasts).

8.3 makeowner

makeowner <spellname> touch <newcaster>

• Description: Transfers ownership of a running spell to another mage, who must have enough resources (spell points, etc.) to maintain it.

8.4 range / power

range <spellname> <mult>
power <spellname> <mult>

• Description: Adjusts the spell’s effective range or power by the given multiplier. Often increases the spell’s resource cost multiplicatively.

8.5 resume

resume [<spellname>] at "<breakpoint>"

• Description: Continues execution of a script after it was paused or altered by an interrupt. Often used in conjunction with if interrupted checks.

9. Spell Cost & Execution

9.1 Cost per Line

Each operator line typically costs 1 resource unit (e.g., 1 spell point) when the spell is cast. The total lines in the script equal the total cost, though some lines (like <spellname>:) may be free or cost adjusted, depending on the exact house rules.

If a script persists indefinitely (e.g., via repeat with no exit condition), those resources stay allocated until the spell ends.

9.2 Duration & Range

A script runs until all lines have executed or a halt is reached. If a repeat loop is used, it may continue for as long as conditions dictate. Typically, the caster must remain within range unless the spell is bind to an object or location.

9.3 Saving Throws

When an SDL effect inflicts damage or a detrimental condition, targets typically make saving throws appropriate to the effect (e.g., DEX, CON, WIS), per the game system’s rules.

10. Example Scripts

10.1 Torch Spell

torch:
bind to touch staffend
create Fire
scale 1"x 1"y 1"z

repeat
  move to staffend
  wait 6 sec
until me "off"

Explanation: Binds the script to a staffend, creates a small flame, and repeatedly repositions it at the staff’s tip every 6 seconds. It ends when the caster says “off.”

10.2 Firewall Spell

firewall:
create Fire myflame
move myflame to 30' pointdir
shape myflame
  lineto 10' pointdir
  fill
scale myflame 10'x 10'y 1"z
wait 3 rounds
destroy myflame

Explanation: Creates a firewall 10 feet high and 10 feet wide, sustaining it for 3 rounds before destroying it.

10.3 Adaptive Boltbox

boltbox:
bind to touch crate
repeat
  if (orc or kobold) 30'
  then if orc 30'
       then create Fire bolt
            move bolt to lookat orc
            scale bolt 1'x 1'y 1'z
       else create Electricity bolt
            move bolt to lookat kobold
            scale bolt 1'x 1'y 1'z

       wait 2 sec
       destroy bolt

  wait 1 sec
until me "off"

Explanation: Any time an orc or kobold approaches within 30 feet of the bound crate, the script creates a bolt of either Fire or Electricity, launches it, then destroys the bolt after 2 seconds. The loop continues until the caster ends it.

End of SDL Reference Manual.

This manual outlines the syntax, operators, and structures used to create spells in the Spell Description Language, allowing flexible, event-driven magic with procedural shaping and real-time alterations.