Global Procs

Immediately terminates the running procedure, providing a stack trace with the given message, output to the /world/var/Log.

Displays a customizable alert message to a user (either a /mob or /client). It accepts a title, message, and up to three buttons as text. If no buttons are specified, the first defaults to "Ok".

If no user is explicitly provided, the current user is used and arguments are shifted. The function checks for a valid connection; if none exists, it returns "OK". Otherwise, it sends the alert and returns the user's interaction.

Returns the character corresponding to a UTF-32 character code - despite the name of this proc, it is not limited to ASCII characters.

world.log << ascii2text(5660) // ᘜ

The returned list is inclusive of the Start and End turfs.

for(var/turf/my_turf in block(1, 1, 1, 10, 10, 10))
    my_turf.icon_state = "green"

This will change the /atom/var/icon_state of every turf, beginning at the turf located at X = 1, Y = 1, Z = 1 and finishing at the turf located at X = 10, Y = 10 and Z = 10, to "green".

The ceiling is the largest integer greater than or equal to the provided number.

world.log << ceil(1.00001) // 2
world.log << ceil(-0.00001) // 0

The canonical form of a given key is composed of lowercase letters between A-Z, numbers between 0-9 and the @ symbol. This is pre-generated on both /mob/var/ckey and /client/var/ckey, based on the user's /client/var/key.

var/my_evil_key = "W0w!!IGotLots-ofFunCharacters!!!InHere@@"

world.log << ckey(my_evil_key) // w0wigotlotsoffuncharactersinhere@@

This is similar to ckey(), however, case is preserved, along with - and _ characters. All other special characters (apart from the @ symbol, as with ckey()) will be removed.

world.log << ckeyEx("OhSoWe'ReKeeping!MyCapitalLetters?Now") // OhSoWeReKeepingMyCapitalLettersNow

Constricts a number between the Low and High values provided. If the number is between those values, it is unchanged. If it exceeds the Low or High values, those will be returned.

world.log << clamp(5, 1, 10) // 5
world.log << clamp(1, 5, 10) // 5
world.log << clamp(15, 1, 10) // 10

When operating on a list, this functions as if clamp() has been run on each entry in the list.

var/my_list = list(1, 2, 3, 4, 5, 6, 7, 8, 9)
for(var/num in clamp(my_list, 1, 5))
    world.log << num // 1, 2, 3, 4, 5, 5, 5, 5, 5

This proc is case insensitive, unlike cmpTextEx(). Any number of arguments can be given to this proc, and it will return 1 if they are all the same.

if(cmptext("letsplayagame", "LETSPLAYAGAME", "letsPlayAGame"))
    world.log << "Yay!" // "Yay!" is printed

Copies characters in the provided string between the Start and End position. By default, the End value will copy the remainder of the string. You can also specify negative positions for the Start or End, which will cause it to work backwards.

world.log << copytext("Foo Bar", 5) // Bar
world.log << copytext("Foo Bar", 1, 4) // Foo

world.log << copytext("Foo Bar", -3) // Bar
world.log << copytext("Foo Bar", -7, -3) // Foo

For non-ASCII strings, where the string position does not necessarily correlate to character position, you will need the _char variant of this proc. copytext_char() works in text elements, and otherwise functions identically.

The source file can be a savefile, a file on the filesystem or a loaded resource, such as an icon.

// resources are specified with 'single quotes'
fcopy('icons/mob.dmi', "temp/mob.dmi")

// "double quotes" specify an external file
fcopy("temp/mob.dmi", "the_void/")

Deletes the specified entry in the file system. If the filename ends with a /, it will recursively delete all contents within the directory.

Determines if the file exists in the file system. Unlike fdel(), this exclusively operates on files - it cannot determine if a directory exists.

if(!fexists("code.dme"))
    world.log << "How did we get here?"

Returns a resource object of the file on the file system. This can then be manipulated using a variety of procs, such as allowing for output to a player using << and browse().

This allows you to read the contents of a file from the file system directly as a string.

The comparison occurs case insensitively - for the case sensitive version, see findlasttextex.md.

world.log << findlasttext("FooFoo", "foo") // 4
world.log << findlasttext("FooFoo", "foo", 3) // 1

The comparison occurs case sensitively - for the case insensitive version, see findlasttext.md.

world.log << findlasttext("FooFoo", "Foo") // 4
world.log << findlasttext("FooFoo", "Foo", 3) // 1

If the Needle provided is a string, the comparison occurs case insensitively. For the case sensitive version, see findtextex.md.

if(findtext("Foo Bar", "foo"))
    world.log << "This succeeds!"

if(findtext("Foo Bar", "Foo", 3))
    world.log << "This does not!" // as the Start is set after the occurence in the string

Negative amounts for the Start or End value count from the end of the string.

if(findtext("Foo Bar", "Bar", -3))
    world.log << "We get here!"

If the Needle provided is a string, the comparison occurs case sensitively. For the case insensitive version, see findtext.md.

if(findtext("Foo Bar", "foo"))
    world.log << "This fails!"

Temporarily replaces the /atom/var/icon, or /atom/var/icon_state, of the specified object for the duration of the animation. This only occurs on the client - the icon or icon_state variable is not actually altered.

/obj/button/Click()
    flick("pressed_animation", src)
    usr << "You pressed me!"

This is non-recursive, and only returns the contents of the directory specified. Names returned are relative to the specified path.

Path must be a directory with a trailing slash.

// given a directory structure like
//
// example
// ├── maps
// │   └── map.dmm
// ├── code.dme
// └── icons
//     ├── icon.dmi
//     └── other_icon.dmi

for(var/item in flist("icons/"))
    world.log << item // "icon.dmi", "other_icon.dmi"

for(var/item in flist("./"))
    world.log << item // "maps/", "code.dme", "icons/"

world.log << floor(0.999999) // 0
world.log << floor(-0.00001) // 1

world.log << fract(0.1234) // 1234
world.log << fract(-0.1234) // -1234

This value can be formatted using time2text().

var/time = ftime("environment.dme") // 7.76174e+09
world.log << time2text(time) // Mon Aug 05 12:58:22 2024

If either object is not on the map, 127 will be returned. If both arguments are the same object, -1 will be returned.

Calculates the step in the opposite direction from the provided object.

Calculates the destination of Ref taking a step in a random direction.

Calculates a path from Ref to Trg, avoiding dense objects. If the target is more than double /world/var/view, null is returned.

for(var/dir in get_steps_to(me, them))
    step(me, dir) // on our way!

Generates a gradient between the specified elements, and retrieves the color at the specified point along the gradient, per the index argument.

world.log << gradient("#FF0000", "#000000", 0.5) // outputs #7F0000, as we have halved the red value

/datum/my_thingy/proc/does_something()

/world/New()
    var/datum/my_thingy/thing = new

    if(hascall(thing, "does_something"))
        world.log << "The thing does something!"

An object that can hear another object is calculated similarly to viewers(), but ignores darkness, as you can still hear in the dark.

The inverse of html_encode(), text that has already been escaped - such as & becoming & - can be decoded into a normal string.

world.log << html_decode("My &amp; strin&#39;g full &gt; of reserved &#39; &lt; characters &quot;.")
// My & strin'g full > of reserved ' < characters \".

Before text can be displayed in a HTML document, certain reserved characters must be encoded, as they have special meaning in HTML. Using html_encode() on the string before it is displayed ensures that it is displayed literally.

world.log << html_encode("My & strin'g full > of reserved ' < characters \".")
// My &amp; strin&#39;g full &gt; of reserved &#39; &lt; characters &quot;.

This constructs a new /icon, similar to using new /icon(), with the specified icon.

Icon files containing multiple icon states can be retrieved. The default, unnamed icon state is retrieved as "".

This constructs a new /image, similar to using new /image().

/obj/hat_giver/Clicked()
    usr.overlays += image('hat.dmi', "big_hat")

The arguments accepted by the proc can be used to override the values inherited from the object, if passed an object in the first argument.

The image is attached to the specified loc, following movable atoms, and can be removed by reassigning the /image/var/loc or deleting the image.

This works for both resource files, and files retrieved via file().

var/my_resource = 'icons/turf.dmi'

if(isfile(my_resource))
    world.log << "It's true!"

This works for both /icon objects, and icon files loaded into the resource cache.

if(isicon('sounds/zworp.ogg'))
    // this will not pass

if(isicon('icons/alien.dmi'))
    // but this will

A valid loc is defined as being an /area, /turf, /obj or /mob. It can be thought of as being ifatom(), and works for any descendent of /atom, including user defined objects.

All children of /atom/movable pass this test, including user defined children, so is similar, but distinct to isobj(loc) || ismob(loc).

For undefined maths operations, a NaN can be returned. A NaN is a special number that is never equal to, less than or greater than any other number, including NaN.

var/what_thing = /mob/player

if(ispath(what_thing))
    world.log << "it's a path..."

if(ispath(what_thing, /mob))
    world.log << "it's some kind of mob..."

if(ispath(what_thing, /mob/player))
    world.log << "it's a player!"

A variable that can be saved is any variable that is not declared as /global, /const, or /tmp.

/datum/a
    var/tmp/foo = "aaa"
    var/bar = "bbb"

/proc/main()
    var/datum/a/thing = new

    world.log << issaved(thing.foo) // 0
    world.log << issaved(thing.bar) // 1

var/mob/my_atom = new /obj(loc) // the variable is declared as a /mob, but we create an /obj
if(istype(my_atom))
    // this will not pass, as the inferred type is different from the actual type

if(istype(my_atom, /obj))
    // this will pass, as we are providing a second argument to test with, which matches the type

For testing paths, use ispath().

All items in the list are stringified - similar to running "[element]" over each element.

    world.log << jointext(list(1, "waaa", 'icons.dmi'), ",") // "1,waaa,icons.dmi"

Negative amounts for the Start or End value count from the end of the list.

This functions similarly to /list/proc/Join().

An array, like ["foo", 1, "bar", 2] will be decoded into a /list, e.g. list("foo", 1, "bar"), 2. Objects, like {"foo": "bar", "do": "re"}, will be decoded into an associated list, e.g. list("foo" = "bar", "do" = "re"). Additional arrays can be embedded into arrays or objects, and an array can hold multiple objects.

var/my_json = @{"
    {
        "some_key": 1231232,
        "some_other_key": "foo",
        "my_third_key": ["an array", "of strings", 12312, "or whatever"],
        "my_final_key": {
            "another_objects_key": "the other objects value"
        }
    }
"}

var/decoded = json_decode(my_json)
for(var/key in decoded)
world.log << key // some_key, some_other_key, my_third_key, my_final_key

Boolean values, such as false and true, will become 0 and 1 respectively, corresponding to the FALSE and TRUE defines.

For both /lists and /matrix objects that are provided as Value, they will be encoded as a JSON array, ie [1,0,0,0,1,0]. An associated list will be encoded as a JSON object.

Any lists included in both normal and associated lists will also be encoded.

If a datum is provided, or is included in a list provided to the proc, they will not be serialized, and instead encoded the same as "[datum]".

var/list/my_list = list("foo" = "bar")
my_list["do_re_mi"] = list("fa_sol_la")
my_list.Add("ti")

world.log << json_encode(my_list)
// {"foo":"bar","do_re_mi":["fa_sol_la"],"ti":null}

The accepted flags are:

world.log << length("Hello, world!") // 13, number of characters

world.log << length(list("Hello,", " world!")) // 2, number of elements in the array

world.log << length(file("foo.txt"))

For non-ASCII strings, you can use the length_char() variant of this proc to correctly handle unicode, which works with character counts.

Use length() - this proc is implemented for legacy reasons as an alias of length.

This is combined with the << output operator to send a link to a client. This will open in the user's browser.

user << link("byond://address:port")

Creates a new /list with the values provided as arguments. If the values provided have both keys and values, an associated list will be created.

for(var/element in list(1, 2, 3))
    world.log << element // 1, 2, 3

var/assoc_list = list("foo" = 1, "bar" = 2, "car" = 3)
for(var/key in assoc_list)
    world.log << key // foo, bar, car
    world.log << assoc_list[key] // 1, 2, 3

This converts an associated list to a parameter string, for use in /client/proc/Topic(), among other places.

var/my_list = list("some_key" = 121, "some_other_key" = "some other value")

world.log << list2params(my_list) // some_key=121&some_other_key=some+other+value

Characters that have a special meaning in a parameter string, such as = and &, will be percent-encoded.

Combined with the << output operator, this informs the client to load the specified resource. If no KeepTime is specified, it is kept for the default duration. If -1 is specified, it will attempt to be loaded indefinitely.

/client/New()
    src << load_resource('ambient.ogg', -1, 'login_music', 120)
    // keep the ambient music forever, the login music for the next 120 seconds

Moves Ref in direction Dir, respecting collision defined by /atom/var/density and /atom/proc/Cross().