DM Language

https://ref.dm-lang.org
Admin
DM (Dream Maker) is a programming language with C/C++-like syntax used to build networked multi-user...
Tokens:229,027
Snippets:2,919
Trust Score:2.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Client Click Proc Example

Source: https://ref.dm-lang.org/client/proc/Click

This is an example of how to implement the client-side Click proc. It logs a message to the user and then calls the default action.

```DM
client
  Click(O)
    usr << "You clicked [O]"
    ..() // do default action
```

--------------------------------

### Example Usage of Topic Proc

Source: https://ref.dm-lang.org/datum/proc/Topic

This example demonstrates how to create a hyperlink that calls the Topic proc with a 'startgame' action. It also shows the implementation of the Topic proc to handle this action.

```DM
mob/verb/test()
   usr << "Click <a href='?src=\ref[src];action=startgame'>here</a>!"
mob/Topic(href,href_list[])
   switch(href_list["action"])
      if("startgame")
         usr << "Starting game..."
```

--------------------------------

### OpenPort Proc Example

Source: https://ref.dm-lang.org/world/proc/OpenPort

This example demonstrates how to override the OpenPort proc to conditionally allow hosting only for subscribed users. It's crucial to call `..()` to ensure the port is actually opened.

```dm
world/OpenPort(port)
  // only allow subscribers to host
  if(host_is_subscribed)
    return ..()

```

--------------------------------

### C++ Wrapper for Byondapi: String List Example

Source: https://ref.dm-lang.org/proc/call_ext

Illustrates reading from a list using Byond_ReadList within a C++ wrapper function. This example is incomplete but shows the setup for processing a list of strings.

```cpp
extern "C" BYOND_EXPORT ByondValueResult addstrings(u4c n, ByondValue v[])
{
    if(!n) return ByondValue(); // not given a list

    std::string str;
    std::vector list = Byond_ReadList(v[0]);

    for(int i=0;
```

--------------------------------

### Example Usage of RenderIcon

Source: https://ref.dm-lang.org/client/proc/RenderIcon

An example demonstrating how to use the RenderIcon proc within a mob's GetFlatIcon proc.

```APIDOC
```
mob/proc/GetFlatIcon()
    return client?.RenderIcon(src)
```
```

--------------------------------

### Mouse Macro Command Example

Source: https://ref.dm-lang.org/skin/macros

This example demonstrates how to construct a mouse macro command using embedded values for action, button, keys, and drag. The `as params` specifier is used for `keys` and `drag` to format them as parameter lists.

```DM
my-mousedown-verb [[src]] [[button]] "keys=[[keys as params]];drag=[[drag as params]]"
```

--------------------------------

### DblClick Proc Implementation (client)

Source: https://ref.dm-lang.org/client/proc/DblClick

Example of how to implement the DblClick proc in the client. It logs a message and then calls the default action.

```client
DblClick(O)
  usr << "You double-clicked [O]"
  ..() // do default action
```

--------------------------------

### Export and Import Savefile Example

Source: https://ref.dm-lang.org/savefile/proc/ExportText

This example demonstrates how to export a player's mob data to a text file using ExportText and then import it back using ImportText. The exported text is also displayed to the user in an HTML-encoded format.

```DM
mob/verb/write()
   var/savefile/F = new()
   var/txtfile = file("players/[ckey].txt")

   F[ckey] << usr

   fdel(txtfile)
   F.ExportText("/",txtfile)

   usr << "Your savefile looks like this:"
   usr << "<pre>[html_encode(file2text(txtfile))]</pre>"

```

```DM
mob/verb/read()
   var/savefile/F = new()
   var/txtfile = file("players/[ckey].txt")

   F.ImportText("/",txtfile)
   F[ckey] >> usr

```

--------------------------------

### Calling a Procedure by Path

Source: https://ref.dm-lang.org/proc/call

This example demonstrates calling a specific procedure using its direct path reference.

```APIDOC
## call(ProcRef)(Arguments)

### Description
Calls a procedure using its direct path reference.

### Method
`call(ProcRef)(Arguments)`

### Parameters
#### Path Parameters
- **ProcRef** (path) - Required - The path to the procedure (e.g., `/proc/MyProc`).
- **Arguments** - Required - The arguments to pass to the procedure.

### Request Example
```
/proc/MyProc(Arg)
   usr << "MyProc([Arg])"
mob
   var
      MyProc = /proc/MyProc
   verb
      call_myproc()
         call(MyProc)("Hello, world!")
```

### Returns
The return value of the proc being called.
```

--------------------------------

### Move to specific coordinates

Source: https://ref.dm-lang.org/proc/locate

This example illustrates using locate with coordinates (x, y, z) to move the user to a precise location on the map.

```dm
usr.Move(locate(1,2,3))
```

--------------------------------

### Create and configure a new menu

Source: https://ref.dm-lang.org/proc/winclone

This example demonstrates creating a new menu from scratch and then adding 'File' and 'Quit' submenus with associated commands. Menus must be assigned to a window using winset to function.

```dm
winclone(usr, "menu", "newmenu")
winset(usr, "newmenu_file", "parent=newmenu;name=File")
winset(usr, "newmenu_quit", "parent=newmenu_file;name=Quit;command=.quit")
```

--------------------------------

### Calculate Distance Between Atoms using bound_pixloc

Source: https://ref.dm-lang.org/proc/bound_pixloc

Use bound_pixloc with direction 0 to get the center of an atom. This example demonstrates calculating the Euclidean distance between the centers of two atoms.

```dm
mob/verb/DistanceTo(atom/A)
    var/my_center = bound_pixloc(src, 0)
    var/A_center = bound_pixloc(A, 0)
    var/vector/V = A_center - my_center
    return length(V)
```

--------------------------------

### Run 'dir' command and display output

Source: https://ref.dm-lang.org/proc/shell

This example executes the 'dir' command with a provided path and writes the output to 'dir.out', then displays the file's content to the user.

```DM
mob/verb/dir(Path as text)
  shell("dir [Path] > dir.out")
  usr << file2text("dir.out")
```

--------------------------------

### Create and configure a new pane with controls

Source: https://ref.dm-lang.org/proc/winclone

This example shows how to create a new pane, set its size, add a label control to it, and then place the pane within a child control so it becomes visible. New windows are invisible by default and require sizing and control placement.

```dm
// Create the pane
winclone(usr, "pane", "newpane")
// Give it a size so we can figure out where to put controls
winset(usr, "newpane", "size=100x100")
// Add controls
winset(usr, "newpane_label", 
       "parent=newpane;pos=0,0;size=100x100;anchor1=0,0;anchor2=100,100")
// Put the pane in a child control where it can be seen
winset(usr, "a_child", "left=newpane")
usr << output("New label", "newpane_label")
```

--------------------------------

### Create a Simple Red to White Color Gradient

Source: https://ref.dm-lang.org/notes/color-gradient

Defines a basic gradient from red to white. The first example uses implicit start and end points, while the second explicitly defines them.

```dm
list("red", "white")
```

```dm
list(0, "red", 1, "white")
```

--------------------------------

### Replace proc with proc replacement

Source: https://ref.dm-lang.org/regex/proc/Replace

This example demonstrates replacing words using a proc. The `word2piglatin` proc is called for each match, converting words to pig latin. It handles capitalization and checks if words start with vowels.

```regex
var/regex/vowels = new("[aeiou]", "i")
// match any word of 2 letters or more
var/regex/piglatin = new("\\b(\\l)(\\l+)\\b", "ig")

// group1 is the first letter, and group2 is everything else
proc/word2piglatin(match, group1, group2)
	// If the word starts with a vowel, just add "ay"
    if(vowels.Find(group1)) return "[match]ay"
    // If the word was capitalized, capitalize the replacement    
    if(group1 == uppertext(group1))
        group1 = lowertext(group1)
        group2 = uppertext(copytext(group2,1,2)) + lowertext(copytext(group2,2))
    return "[group2][group1]ay"
 
mob/verb/PigSay(msg as text)
    msg = html_encode(msg)
    world << piglatin.Replace(msg, /proc/word2piglatin)
```

--------------------------------

### Setting up a Lighting Plane and Spotlight

Source: https://ref.dm-lang.org/atom/var/appearance_flags

This example demonstrates how to create a lighting plane and a spotlight effect. The lighting plane uses `BLEND_MULTIPLY` and `PLANE_MASTER` with `NO_CLIENT_COLOR` to apply lighting, while the spotlight uses `BLEND_ADD` to add light to specific areas. Objects on plane 2 are treated as lights.

```dm
obj/lighting_plane
    screen_loc = "1,1"
    plane = 2
    blend_mode = BLEND_MULTIPLY
    appearance_flags = PLANE_MASTER | NO_CLIENT_COLOR
    // use 20% ambient lighting; be sure to add full alpha
    color = list(null,null,null,null,"#333f")
    mouse_opacity = 0    // nothing on this plane is mouse-visible
 
image/spotlight
    plane = 2
    blend_mode = BLEND_ADD
    icon = 'spotlight.dmi'  // a 96x96 white circle
    pixel_x = -32
    pixel_y = -32
 
mob/Login()
    ..()
    client.screen += new/obj/lighting_plane
    overlays += /image/spotlight
```

--------------------------------

### Using the Dereference Operator (*)

Source: https://ref.dm-lang.org/operator/asterisk/pointer

This example demonstrates how to use the dereference operator (*) to modify pointer values within different proc scopes. It also shows how to use the '&' operator to get a pointer and then dereference it to display the value.

```dm
atom/proc/PixelPos(px, py)	// get an exact step position
	*px = (x-1) * 32	// this code assumes a 32x32 icon size
	*py = (y-1) * 32

atom/movable/PixelPos(px, py)	// get an exact step position
	..()
	*px += step_x	// this code assumes a 32x32 icon size
	*py += step_y

mob/verb/WhereAmI()
	var/X, Y
	PixelPos(&X, &Y)
	usr << "You are at [X],[Y] on level [z]"
```

--------------------------------

### Initializing Lists with Data

Source: https://ref.dm-lang.org/list

Shows how to use the 'list()' proc to initialize a list with specific data elements.

```dm
var/list/L
L = list("futz",3)   // L contains: ("futz", 3)
```

--------------------------------

### Define Object Type with Absolute Path

Source: https://ref.dm-lang.org/operator/path/slash

Use an absolute path starting with '/' to define the type of object to create, ensuring it's independent of the current code location. This example shows how to reference a specific corpse type.

```dm
obj
   var
      poison
      nutrition

   corpse
      frog
         nutrition = 10
      spider
         nutrition = 6
         poison = 5
mob
   var
      corpse = /obj/corpse
   Die()
      new corpse(src.loc) //create the corpse here
      del src

   spider
      corpse = /obj/corpse/spider
   frog
      corpse = /obj/corpse/frog
```

--------------------------------

### Declaring and Initializing Lists

Source: https://ref.dm-lang.org/list

Demonstrates how to declare list references, assign them to existing lists, and create new lists with or without an initial size.

```dm
var/list/L         // list reference
L = world.contents // assign to existing list
L = new/list()     // make a new list
L = new()          // make a new list (implicit type)
L.Add("futz")      // L contains: "futz"
del(L)             // delete L
```

--------------------------------

### Uncrossed proc example

Source: https://ref.dm-lang.org/atom/proc/Uncrossed

Example of implementing the Uncrossed proc on a pressure plate. It checks if any mobs are currently on the plate before releasing.

```DM
obj/pressure_plate
   Uncrossed(O)
      // if no other mobs are standing on it...
      if(!(locate(/mob) in bounds()))
         // do something
         Release()

```

--------------------------------

### block(Start, End)

Source: https://ref.dm-lang.org/proc/block

Defines a 3D block using two turf objects as the start and end points (inclusive).

```APIDOC
## block(Start, End)

### Description
Returns the list of turfs in the 3D block defined by Start and End (inclusive).

### Args
* `Start`: A turf to be the lower-left corner of the block.
* `End`: A turf to be the upper-right corner of the block.

### Example
```
world
   maxx = 20
   maxy = 20

mob/verb/block_test()
   var/turf/T
   for(T in block(locate(1,1,1), locate(10,10,1)))
      T.text = " "
```
```

--------------------------------

### Do...While Loop Example

Source: https://ref.dm-lang.org/proc/do

Demonstrates the basic syntax and execution of a 'do...while' loop. The loop continues as long as the condition 'i' is non-zero. Ensure the condition eventually becomes false to avoid an infinite loop.

```dm
var/i = 3
do
  world << i--
while(i)
```

--------------------------------

### Rotate Icon Example

Source: https://ref.dm-lang.org/proc/turn/icon

This example demonstrates rotating an icon clockwise and then counter-clockwise. Ensure the icon is square for the rotation to apply correctly.

```mob
mob/verb/drink()
   //this effect is very confusing!
   usr.icon = turn(usr.icon,90)
   usr << "Woah!  That stuff is powerful!"
   sleep(200)
   usr.icon = turn(usr.icon,-90)
```

--------------------------------

### C-like Switch Syntax with Fallthrough

Source: https://ref.dm-lang.org/proc/switch

Illustrates how to enable C-like switch syntax using #pragma syntax. This example shows the use of 'case', 'default', and 'break' statements, including fallthrough behavior.

```DM
#pragma push
#pragma syntax C switch

mob/proc/Greeting(friend)
    switch(roll(6))
        case 4:
            friend << "I'm [name]. \"...
            // fall through to cases 1 and 2
        case 1,2:
            friend << "Hi!"
            break
        case 3:
            friend << "Hello there!"
        default:
            friend << "Yo."
            break

#pragma pop
```

--------------------------------

### Copying a file using fcopy

Source: https://ref.dm-lang.org/proc/fcopy

This example demonstrates copying an uploaded file to 'world.dm', recompiling the world, and then rebooting it. Use with caution as it allows player-uploaded code execution.

```dm
mob/verb/change_world(F as file)
  fcopy(F,"world.dm")
  shell("DreamMaker world")
  world.Reboot()
```

--------------------------------

### ClearMedal Proc Example

Source: https://ref.dm-lang.org/world/proc/ClearMedal

This example demonstrates how to use ClearMedal to remove the 'Pacifist' medal from a killer mob. It is wrapped in spawn() to prevent game-wide delays.

```dm
mob/NPC
   Die(mob/killer)
      spawn()
         if(ismob(killer) && killer.key)
            world.ClearMedal("Pacifist", killer)
```

--------------------------------

### Importing and Loading a Client-Side File

Source: https://ref.dm-lang.org/client/proc/Export

This example shows how to import a file previously exported to the client and load it as a savefile. This is typically done in the client's New() proc to restore game state.

```DM
client/New()
   var/client_file = Import()
   if(client_file)
      var/savefile/F = new(client_file) //open it as a savefile
      F >> usr  //read the player's mob
   return ..()

```

--------------------------------

### list.Cut

Source: https://ref.dm-lang.org/list/proc/Cut

Removes elements from a list between the specified start and end positions. The default end position removes all elements from the start position to the end of the list.

```APIDOC
## list.Cut

### Description
Removes the elements between list[Start] and list[End-1], decreasing the size of the list appropriately. The default end position of 0 stands for the position immediately after the end of the list, so by default the entire list is deleted.

### Method
`list.Cut(Start=1, End=0)`

### Parameters
#### Arguments
* `Start` (integer) - The list position in which to begin the cut.
* `End` (integer) - The list position immediately following the last element to be removed.

### See also
> Insert proc (list)
```

--------------------------------

### Saving a File with client.Export

Source: https://ref.dm-lang.org/client/proc/Export

This example demonstrates how to create a savefile and export it to the client's computer using the client.Export proc. The file will replace any existing file with the same world.hub value.

```DM
mob/verb/save()
   var/savefile/F = new()
   F << usr     //write the player's mob
   usr.client.Export(F)

```

--------------------------------

### Turf Entered Action

Source: https://ref.dm-lang.org/atom/proc/Entered

Example of how a turf might handle an object entering its area. This specific example shows a pit turf notifying the entering object.

```dm
turf/pit
   Entered(O)
      O << "OUCH.  You fell in a pit!"
```

--------------------------------

### Set Configuration with Specific Space

Source: https://ref.dm-lang.org/world/proc/GetConfig

This example shows how to set a configuration value within a specific configuration space, such as 'APP'. This is useful for managing settings across different application contexts.

```DM
world.SetConfig("APP/keyban",...)
```

--------------------------------

### Spawn Particles with .add-particles

Source: https://ref.dm-lang.org/notes/particles

Use the winset() function to execute the .add-particles command from the server. This example spawns 100 particles for the 'src' particle set immediately.

```dm
winset(player, null, list(command=".add-particles \ref[src] 100"))
```

--------------------------------

### Asynchronous Byondapi: Sleep 2 Seconds Example

Source: https://ref.dm-lang.org/proc/call_ext

An example of an asynchronous function that sleeps for 2 seconds before returning a value using Byond_Return. It spawns a new thread to handle the delay.

```cpp
extern "C" BYOND_EXPORT void Sleep2sec(u4c n, CByondValue v[], CByondValue waiting_proc)
{
    std::thread t([](CByondValue waiting_proc) {
        CByondValue result;
        std::this_thread::sleep_for(std::chrono::seconds(2));
        ByondValue_SetNum(&result, 1);
        Byond_Return(waiting, result);
    }, waiting_proc);
    t.detach();
}
```

--------------------------------

### Create and Query SQLite Database

Source: https://ref.dm-lang.org/database

Instantiate a database connection and execute a parameterized query. Use `q.Execute(db)` to run the query and `q.NextRow()` to check for results. `q.GetRowData()` returns query results as a list.

```dm
var/database/db = new("mydb.db")
var/database/query/q = new("SELECT * FROM my_table WHERE name=?", usr.key)

if(q.Execute(db) && q.NextRow())
    // returns a list such as list(name="MyName", score=123)
    return q.GetRowData()
// no data found
return null
```

--------------------------------

### Get Derived Object Types

Source: https://ref.dm-lang.org/proc/typesof

Use typesof to get a list of all types derived from a base object type, including the base type itself. This is useful for iterating over related object types.

```dm
obj/fruit
  apple
  peach
  mango
var/list/fruit_types = typesof(/obj/fruit)
```

--------------------------------

### BYOND Winget URL Example

Source: https://ref.dm-lang.org/skin/control/browser/winset

This is an example of a URL used for the winget operation. It specifies the callback function, the control ID, and the properties to retrieve. Ensure any special characters in IDs or properties are URL-encoded.

```URL
byond://winget?callback=wgcb&id=button1&property=is-checked,size,background-color
```

--------------------------------

### Example: Item Shop using PayCredits

Source: https://ref.dm-lang.org/world/proc/PayCredits

This proc demonstrates how to use PayCredits to deduct credits for an item purchase in an item shop. It handles cases where the shop is unavailable, the player lacks sufficient credits, or the purchase is successful. It also shows how to retrieve the player's current credits using GetCredits.

```dm
mob/proc/ItemShop()
    var/items = list("Get credits!", "Magic sword"=10, "Skeleton key"=50)
    var/choices[0]
    var/item,price
    for(item in items)
        price = items[item]
        choices["[item]: [price] credit\s"] = item
 
    var/credits = world.GetCredits(key)
    if(isnull(credits))
        src << "Sorry, the item shop isn't available right now."
        return
 
    var/choice = input(src,\ 
      "You have [credits] credit\s. What would you like to purchase?",\ 
      "Item Shop")\ 
      as null|anything in choices
    if(!choice) return  // cancel
 
    if(choice == "Get credits")
        src << link("http://www.byond.com/games/Author/MyGame/credits")
        return
 
    item = choices[choice]
    price = items[item]
    if(!price) return
 
    src << "Contacting item shop..."
    var/result = world.PayCredits(name, price, "Item shop: [item]")
 
    if(isnull(result))
        src << "Sorry, the item shop isn't available right now."
    else if(!result)
        src << "You need [price-credits] more credit\s to buy [item]."
    else
        src << "You bought \a [item]!"

        // Now give the user the item and save their character
        // These procs are for you to define
        src.AddEquipment(item)
        src.SaveCharacter()
```

--------------------------------

### Simple Projection Matrix Example

Source: https://ref.dm-lang.org/notes/projection-matrix

Provides a specific example of a 4x4 projection matrix where the 'D' value controls the camera's distance from z=0, affecting the perceived size of objects based on their z-coordinate.

```mathematica
1  0  0  0
0  1  0  0
0  0  1  1/D
0  0  0  1
```

--------------------------------

### Configure Client and World Settings

Source: https://ref.dm-lang.org/client/var/show_map

This example demonstrates how to disable the map display by setting `show_map` to 0. It also shows how to set `world.view` to 0 to restrict interaction to the current turf and `mob.density` to 0 to allow multiple mobs in a room. This combination is useful for text-based MUDs.

```dm
client
   show_map = 0 //Text is best!
world
   view = 0     //You can interact only with objects in same turf.
mob
   density = 0  //Allow multiple mobs in a room.
```

--------------------------------

### block(StartX, StartY, StartZ, EndX, EndY, EndZ)

Source: https://ref.dm-lang.org/proc/block

Defines a 3D block using XYZ coordinates for the start and end points (inclusive). End coordinates can be omitted and will default to the start coordinates.

```APIDOC
## block(StartX, StartY, StartZ, EndX, EndY, EndZ)

### Description
Returns the list of turfs in the 3D block defined by Start and End coordinates (inclusive).

### Args
* `StartX, StartY, StartZ`: XYZ coordinates of the lower-left corner of the block.
* `EndX, EndY, EndZ`: XYZ coordinates of the upper-right corner of the block. If EndX, EndY, or EndZ are omitted, they default to StartX, StartY, or StartZ respectively.

### Example
```
world
   maxx = 20
   maxy = 20

mob/verb/block_test()
   var/turf/T
   for(T in block(1,1,1, 10,10))
      T.text = " "
```
```

--------------------------------

### Check Game Resource Integrity with MD5

Source: https://ref.dm-lang.org/proc/md5

This example shows how to use md5() to verify the integrity of game resources like default icons or entire resource files. It compares the current hash of a file with a pre-computed hash to detect modifications.

```DM
var/hash = "(insert hash value here)"	// Compute this ahead of time

// Check that the cached default icon is still the same
if (md5('default.dmi') != hash)
  world << "The default icon has been modified!"

// Or check that the entire game resource file is pristine
if (md5(file("mygame.rsc")) != hash)
  world << "The game resources have been modified!"
```

--------------------------------

### Play a Sound File

Source: https://ref.dm-lang.org/sound

Create a sound datum from a WAV file and send it to the player. The client will play the first compatible sound if a list is provided.

```dm
var/sound/S = sound('bubbles.wav')
usr << S
```

--------------------------------

### Display Help Page in Popup Window

Source: https://ref.dm-lang.org/proc/browse

This example shows how to display a custom HTML help page in a dedicated popup window named 'help'.

```dm
var/const/help = "
<html>
<head><title>Help!</title></head>
<body>
 
You are beyond help! 
</body>
</html>
"
client/verb/help()
   usr << browse(help,"window=help")
```

--------------------------------

### URL Encode Example

Source: https://ref.dm-lang.org/proc/url_encode

This example demonstrates how to use url_encode to create clickable links with encoded user keys and messages. The default format=0 is used, which converts spaces to '+' and escapes most characters, suitable for query strings.

```DM
mob/verb/Private(M as mob in players, T as text)
   if(!client || !M || !M.client || !T) return
   usr << "\[To <a href='?msg=[url_encode(M.key)]'>[M.name]</a>\] [T]"
   M << "\[From <a href='?msg=[url_encode(key)]'>[name]</a>\] [T]"
```

--------------------------------

### Route Topic to Another Object with Parameters

Source: https://ref.dm-lang.org/client/proc/Topic

This example shows how to route a topic request to another object using the 'src' parameter and pass additional data via 'action'. It's the recommended way to handle topics, allowing for custom logic in the target object.

```dm
mob/Login()
   src << "Click <a href='?src=\ref[src];action=startgame'>here</a> to start."
   return ..()

mob/Topic(href,href_list[])
   switch(href_list["action"])
      if("startgame")
         usr << "Starting game..."
      else
         return ..()
```

--------------------------------

### Get Individual Player Scores

Source: https://ref.dm-lang.org/world/proc/GetScores

Use this when you need to retrieve specific score fields for a single player. The key can be a player's name or character name and is case-insensitive. Leave fields blank to get all associated data.

```dm
mob/var/scores_found
mob/var/score = 0

mob/Login()
  ..()
  spawn()
    var/scores = world.GetScores(key)
    scores_found = !isnull(scores)
    if(scores)
      var/list/params = params2list(scores)
      if(params["Score"])
        score = text2num(params["Score"])
        src << "You have [score] point\s!"
```

--------------------------------

### Create and Open Files with Names

Source: https://ref.dm-lang.org/savefile/var/name

Demonstrates creating temporary files and opening existing files with specified names using the 'new()' function. The '.name' attribute retrieves the file's name.

```dm-lang
F1 = new()         // create a temp file
F2 = new("myfile") // open "myfile"

world << "F1.name = [F1]"
world << "F2.name = [F2]"
```

--------------------------------

### Goto Statement Example

Source: https://ref.dm-lang.org/proc/goto

Demonstrates jumping to a labeled node 'End' within a proc. Use goto judiciously to avoid spaghetti logic; prefer loops and break/continue statements for simpler control flow.

```dm
goto End
world << "ERR"
End
world << "The end"
```

--------------------------------

### C++ Byondapi Library: Numeric Average Example

Source: https://ref.dm-lang.org/proc/call_ext

This C++ example defines an 'average' function that calculates the arithmetic mean of numeric Byondapi values passed as arguments. It handles cases where no numeric arguments are provided by returning null.

```cpp
extern "C" BYOND_EXPORT CByondValue average(u4c n, CByondValue v[])
{
    CByondValue result;
    float total = 0.0f;
    int count = 0;
    for(int i=0; i<n; i++) {
        if(!ByondValue_IsNum(v[i])) continue;
        total += ByondValue_GetNum(v[i]);
        ++count;
    }
    if(count) ByondValue_SetNum(&result, total / count);
    else ByondValue_Clear(&result); // return null on failure
    return result;
}

```

--------------------------------

### C++ Byondapi Library: String Concatenation Example

Source: https://ref.dm-lang.org/proc/call_ext

This C++ example demonstrates a library function 'merge' that concatenates multiple Byondapi values into a single string. It handles dynamic buffer resizing and potential memory allocation failures.

```cpp
#include <byondapi.h>
#include <stdlib.h>
#include <string.h>

// a different take on the merge example above
extern "C" BYOND_EXPORT CByondValue merge(u4c n, CByondValue v[])
{
    CByondValue result;
    u4c buflen = 1024;  // initial size of buffer
    u4c totallen = 0;   // length of total string so far (not including trailing null)
    char *buf = (char*)malloc(buflen);

    if(!buf) {  // we couldn't allocate memory
        ByondValue_Clear(&result);
        return result;
    }

    for(int i=0; i<n; i++) {
        u4c len = buflen - totallen;    // # of bytes left in buffer
        bool success = Byond_ToString(v[i], buf+totallen, &len);
        // on success, len is filled with # of bytes written (including trailing null)
        if(success) {
            totallen += (len-1);
        }
        // if we failed but len > 0, it's the new size of the buffer we need
        else if(len) {
            len = (len + 1023) & ~1023; // round up to 1K increments
            char *newbuf = (char *)mallloc(len);
            if(!newbuf) {   // out of memory; stop here
                ByondValue_Clear(&result);
                return result;
            }
            memcpy(newbuf, buf, totallen+1);    // include trailing null in copy
            free(buf);
            buf = newbuf; buflen = len;
            --i;  // retry Byond_ToString() for this argument
        }
        // if we failed but len == 0, there was an error
        else {
            free(buf);
            ByondValue_Clear(&result);
            return result;
        }
    }
    ByondValue_SetStr(&result, buf);    // create a new internal string
    free(buf);  // free the buffer
    return result;
}

```

--------------------------------

### Create a basic window clone

Source: https://ref.dm-lang.org/proc/winclone

Use winclone to create a clone of a window, pane, menu, or macro set. The original object from the skin file is used as a template. The clone is specific to the player.

```dm
winclone(usr, "templatewindow", "clonedwindow")
```

--------------------------------

### Make HTTP GET Request

Source: https://ref.dm-lang.org/world/proc/Export

Fetches content from a web server using an HTTP GET request. The result includes HTTP headers and the content of the requested resource. This action will cause the caller to sleep while waiting for the request to finish.

```dm
mob/verb/test()
    var/http[] = world.Export("http://www.byond.com")
 
    if(!http)
        usr << "Failed to connect."
        return

    usr << "HTTP Header:"
    for(var/V in http)
        usr << "[V] = [http[V]]"
    usr << "\n"

    var/F = http["CONTENT"]
    if(F)
        usr << html_encode(file2text(F))
```

--------------------------------

### Play Sound Files with sound()

Source: https://ref.dm-lang.org/proc/sound

Demonstrates playing different sound files with various parameters. The `sound()` function is optional when no additional parameters are needed, and the `<<` operator can be used directly.

```dmscript
usr << 'giggle.wav' // play a giggle once
```

```dmscript
usr << sound('gigue.midi',1) // repeat gigue
```

```dmscript
usr << sound('boom.wav', volume=50) // play an explosion at half volume
```

--------------------------------

### Synchronizing Sound with Animation

Source: https://ref.dm-lang.org/proc/animate

This example demonstrates how to play a sound effect synchronized with an animation sequence. The `command` argument in `animate` is used to execute a client-side command, and `[[*]]` expands to the object's reference.

```DM
obj/bouncing_ball/New()
    // this is only here to ensure the sound is included in resources
    var/static/bounce = 'bounce.ogg'
    var/sound_command = @".sound 'bounce.ogg' atom=[[*]] transform=1,0,0,0,0.707,0.707,0,0,0 falloff=10"
 
    animate(src, pixel_z=16, easing=QUAD_EASING|EASE_OUT, time=5, loop=-1)
    animate(pixel_z=0, command=sound_command, easing=QUAD_EASING|EASE_IN, time=5)
```
Tokens:
Raw