LOTJ Lua API

• Index

Contents

• Global functions
• Class Room

Modules

• area
• char_proto
• character
• clan
• core
• events
• exit
• furniture
• hyperwall
• obj_proto
• object
• planet
• room
• ship
• ship_template
• space_spawn
• starsystem
• structure
• timer

Topics

• Introduction
• Lua Basics
• Creating an lprog
• Before and After: Lylek Drone
• gptnpcs

Examples

• mixrmastr-bartender-droid.lua
• yatta-invisible-market.lua

Module room

Functions for rooms

Global functions

Room.getFromVNum (vnum)

finds a room by vnum

Class Room

room:characters ()	get an iterator over characters in the room
room:countNPC ()	returns the number of mobs in the room.
room:countPC ()	returns the number of players in the room.
room:echo (message, args)	send a message to the occupants of a room.
room:exits ()	get an iterator over exits in the room
room:findChar (args, asChar)	find a character in this room by name.
room:findObj (args, asChar)	find a object in this room by name.
room:force (to)	convenient handle to use the Agent within a room to perform actions
room:furniture ()	get an iterator over furniture in the room
room:getCharByVNum ()	returns the first character found in this room with the given vnum.
room:getDescription ()	return the room's description
room:getExit (name)	get an exit by keyword/direction.
room:getInArea ()	return the area containing the room
room:getInShip ()	return the ship this room is part of
room:getInStructure ()	return the structure this room is part of
room:getMaxShipClass ()	return the maximum ship class number for this room
room:getMinShipClass ()	return the minimum ship class number for this room
room:getName ()	return the room's name
room:getOnPlanet ()	get the planet for this room.
room:getOpenExits (forMob)	gets a table of the currently accessible exits from a room (no closed door, not window or hidden)
room:getShipCapacity ()	return the ship size capacity for this room.
room:getShipSizeUsed ()	return the combined size of all ships and frames in the room.
room:getTunnel ()	return the room's tunnel
room:getVNum ()	return the room's vnum
room:getVar (varName, default)	get a room's variable by name
room:getVarTimer (varName)	get the remaining time on a room's variable, by name
room:hasFlag (flag)	get whether a flag is set on this room.
room:hookKnockout (callback)	registers a hook function to run when a character gets knocked out due to damage
room:isPublicSpace ()	returns whether this room is accessible by hail or public landing pad.
room:objects ()	get an iterator over objects in the room
room:onAct (message, callback)	registers a function to run when the given action message is shown in the room.
room:onCommand (command, callback)	registers a function to run when a character (player or NPC) enters a custom command.
room:onDrop (callback)	registers a function to run when a character drop an object in the room.
room:onEnter (callback)	registers a function to run when a character (player or NPC) enters a room.
room:onLeave (callback)	registers a function to run when a character (player or NPC) leaves a room.
room:onLook (keyword, callback)	registers a function to run when a character looks, either at the room or a given keyword.
room:onRandom (chance, callback)	registers a function with a chance to run every main tick (52-87 seconds, random).
room:onSpeech (message, callback)	registers a function to run when the given text is spoken in the room.
room:onTime (hour, callback)	registers a function to run every time the hour changes to a certain value.
room:randomPlayer ()	chooses a random player in the room and returns them.
room:setAccessDoor (dir, keywords, accessCheck)	sets up a voice-activated locked door.
room:setClanAccessDoor (dir, keywords, clanName)	sets up a voice-activated locked door which works for members of the given clan.
room:setClanLeaderAccessDoor (dir, keywords, clanName)	sets up a voice-activated locked door which works for leader/first/second of the given clan.
room:setDescription (description)	set the description of a room.
room:setFlag (flag, value)	set a flag on this room.
room:setName (name)	set the name of a room.
room:setTunnel (value)	set the room's tunnel value
room:setVar (varName, value, ttl)	set a variable on a room
room:ships ()	get an iterator over ships in the room

Global functions

Room.getFromVNum (vnum)

finds a room by vnum

Parameters:

• vnum number the room vnum

Returns:

Room the room, or nil if not found

Class Room

room:characters ()

get an iterator over characters in the room

Returns:

an iterator of Character

Usage:

for char in room:characters() do
  -- do something
end

room:countNPC ()

returns the number of mobs in the room.

Returns:

integer the number of mobs in the room.

room:countPC ()

returns the number of players in the room.

Returns:

integer the number of players in the room.

room:echo (message, args)

send a message to the occupants of a room.

Parameters:

• message string the message to send. Can contain tokens referring to subsequent arguments, substituted appropriately for viewers.
• args any any number of arguments corresponding to the {#} tokens in the message. {1} will refer to the first arg, etc.

Usage:

self:onEnter(function(self, ch)
  -- This will show 'focus on you ... illuminates your features' to the character who entered.
  -- For anyone else, it will show their name and correct possessive pronoun.
  self:echo("A security camera turns to focus on {1} and a spotlight illuminates {1.s} features.", ch)
end)

room:exits ()

get an iterator over exits in the room

Returns:

an iterator of Exit

Usage:

for exit in room:exits() do
  -- do something
end

room:findChar (args, asChar)

find a character in this room by name.

Parameters:

• args string the name(s) to search for. Just like targeting characters ingame, can use multiple words to get exact matches against a mob with multiple keywords.
• asChar Character Optional, the character to search as. If specified, matches names as this character would see them and will not return targets they can't see.

Returns:

Character a valid matching target, or nil if no match was found

Usage:

• self:onCommand("tag", function(self, ch, args)
    -- We want to let them do "tag <target>", so look for the target they entered by name
    local target = self:findChar(args, ch)
    if not target then
      ch:echoAt("You don't see '{1}' here.", args)
    else
      target:echoAt("TAG! You're it!")
      ch:echoAt("You tagged {1}!", target)
    end
  end)

• -- Get the character named "Sherlock" in this room, regardless of restrung armor, invis state, etc.
  local sherlock = self:findChar("sherlock")

room:findObj (args, asChar)

find a object in this room by name.

Parameters:

• args string the name(s) to search for. Just like targeting objects ingame, can use multiple words to get exact matches against an object with multiple keywords.
• asChar Character Optional, the character to search as. If specified, matches names as this character would see them and will not return objects they can't see.

Returns:

Object a valid matching target, or nil if no match was found

Usage:

• self:onCommand("enable", function(self, ch, args)
    -- We want to let them do "enable <object>", so look for the object they entered by name
    local obj = self:findObj(args, ch)
    if not obj then
      ch:echoAt("You don't see '{1}' here.", args)
    else
      obj:echo("{1} has been enabled by {2}.", obj, ch)
    end
  end)

• -- Get the object named "controlpanel" in this room regardless of hidden/invis state, etc.
  local panel = self:findObj("controlpanel")

room:force (to)

convenient handle to use the Agent within a room to perform actions

Parameters:

• to command force the agent to perform

room:furniture ()

get an iterator over furniture in the room

Returns:

an iterator of Furniture

Usage:

for furn in room:furniture() do
  -- do something
end

room:getCharByVNum ()

returns the first character found in this room with the given vnum.

Returns:

Character the first character in this room with the given vnum, or nil if none are there

room:getDescription ()

return the room's description

Returns:

string the room's description, including color codes

room:getExit (name)

get an exit by keyword/direction.

Parameters:

• name string the direction or exit keyword

Returns:

Exit an exit matching the name, or nil if one could not be found.

room:getInArea ()

return the area containing the room

Returns:

Area the area containing the room

room:getInShip ()

return the ship this room is part of

Returns:

Ship the ship containing the room, or nil if it's not part of a ship

room:getInStructure ()

return the structure this room is part of

Returns:

Structure the structure containing the room, or nil if it's not part of a structure

room:getMaxShipClass ()

return the maximum ship class number for this room

Returns:

number the maximum ship class supported by this room

room:getMinShipClass ()

return the minimum ship class number for this room

Returns:

number the minimum ship class supported by this room

room:getName ()

return the room's name

Returns:

string the room's name, including color codes

room:getOnPlanet ()

get the planet for this room.

Returns:

Planet the planet the room is on, or nil if not on one

room:getOpenExits (forMob)

gets a table of the currently accessible exits from a room (no closed door, not window or hidden)

Parameters:

• forMob bool if true, only returns exits which mobs are allowed through (exit and target room aren't flagged nomob)

Returns:

table the list of exits matching from this room, empty if none were valid

Usage:

-- For a mob lprog, we want our mob to wander randomly, so pick a random available mob-friendly exit.
self:onRandom(100, function(self)
  local room = self:getInRoom()
  local exits = room:getOpenExits(true)

  -- No available exits? Do nothing.
  if #exits == 0 then return end

  -- Pick a random exit, then force the mob to use the exit direction command.
  local randomExit = exits[math.random(#exits)]
  self:force(randomExit:getName())
end)

room:getShipCapacity ()

return the ship size capacity for this room. Accounts for the redit-based size limit, not any hangar size limit for ships.

Returns:

number the total number of combined ship size supported by this room

room:getShipSizeUsed ()

return the combined size of all ships and frames in the room.

Returns:

number the combined size of all ships and frames in the room

room:getTunnel ()

return the room's tunnel

Returns:

number the room's tunnel value

room:getVNum ()

return the room's vnum

Returns:

number the room's vnum

room:getVar (varName, default)

get a room's variable by name

Parameters:

• varName string the name of the variable to get
• default an optional default value (string, number, or boolean) to return if the variable is unset

Returns:

the value, or the default or nil if it's not set. Can be a bool, number, or string.

room:getVarTimer (varName)

get the remaining time on a room's variable, by name

Parameters:

• varName string the name of the variable whose timer you want to get

Returns:

the integer value of seconds remaining in the timer, or 0 if it's expired, or nil if the variable is not set.

room:hasFlag (flag)

get whether a flag is set on this room.

Parameters:

• flag string The flag to check for

Returns:

boolean True if the flag is set, false otherwise

Usage:

if room:hasFlag("silence") do
  ch:echoAt("You can't hear anything!")
end

room:hookKnockout (callback)

registers a hook function to run when a character gets knocked out due to damage

Parameters:

• callback func the function to run, taking arguments: 1. the Room 2. the Character who was knocked out the command

Returns:

boolean true if the hook should supercede the default behavior, false otherwise

Usage:

self:hookKnockout(function(self, ch)
  -- boost hp so they don't go down
  ch:setHP(100)
  ch:echoAt("You feel a surge of adrenaline and manage to stay on your feet!")
  return true
end)

room:isPublicSpace ()

returns whether this room is accessible by hail or public landing pad.

Returns:

bool true if there's a path to a hail point or public landing pad, false otherwise

room:objects ()

get an iterator over objects in the room

Returns:

an iterator of Object

Usage:

for obj in room:objects() do
  -- do something
end

room:onAct (message, callback)

registers a function to run when the given action message is shown in the room.

Parameters:

• message string the message to trigger on
• callback func the function to run, taking arguments: 1. this Room 2. the Character who did the action 3. the full text of the action message

Usage:

self:onAct("grips the piloting controls", function(self, actor, fullText)
  actor:echoAt("The console beeps loudly and the controls are disabled.")
  actor:force("pilot")
end)

room:onCommand (command, callback)

registers a function to run when a character (player or NPC) enters a custom command.

Parameters:

• command string the command name
• callback func the function to run, taking arguments: 1. the Room 2. the Character who entered the command 3. the argument they entered to the command, if any

Usage:

self:onCommand("keypad", function(self, ch, argument)
  ch:echoAt("You input the following code into the keypad: "..argument)
end)

room:onDrop (callback)

registers a function to run when a character drop an object in the room.

Parameters:

• callback func the function to run, taking arguments: 1. the Room 2. the Object which was dropped 3. the Character dropping the object

Usage:

self:onDrop(function(self, obj, ch)
  ch:echoAt("An alarm rings out and a voice blares over the loudspeaker blaming you for littering "..obj:getShortDescription())
end)

room:onEnter (callback)

registers a function to run when a character (player or NPC) enters a room.

Parameters:

• callback func the function to run, taking arguments: 1. the Room 2. the Character entering the room 3. the Room they came from

Usage:

self:onEnter(function(self, ch, fromRoom)
  ch:echoAt("As you enter from "..fromRoom:getName()..", you notice something interesting!")
end)

room:onLeave (callback)

registers a function to run when a character (player or NPC) leaves a room.

Parameters:

• callback func the function to run, taking arguments: 1. the Room 2. the Character entering the room

Usage:

self:onLeave(function(self, ch, toRoom)
  ch:echoAt("Right before you leave for "..toRoom:getName()..", you hear a loud noise!")
end)

room:onLook (keyword, callback)

registers a function to run when a character looks, either at the room or a given keyword.

Parameters:

• keyword string the keyword the character must look at to trigger the function. To trigger on using just plain "look", including when they enter a room, use an empty string. If it's not empty, this will only be matched if nothing else in the room matched the same keyword.
• callback func the function to run, taking arguments: 1. the Room 2. the Character who looked

Usage:

• self:onLook("", function(self, ch)
    ch:echoAt("As you look around, you notice something strange behind the &kcurtain&k.")
  end)

• self:onLook("curtain", function(self, ch)
    ch:echoAt("You look behind the curtain and find a hidden treasure!")
  end)

room:onRandom (chance, callback)

registers a function with a chance to run every main tick (52-87 seconds, random).

Parameters:

• chance integer the chance, 1-100, that the trigger will fire on a given tick
• callback func the function to run, taking arguments: 1. this Room

Usage:

self:onRandom(25, function(self)
  -- Do stuff
end)

room:onSpeech (message, callback)

registers a function to run when the given text is spoken in the room.

Parameters:

• message string the message to trigger on
• callback func the function to run, taking arguments: 1. this Room 2. the Character who spoke 3. the full text spoken

Usage:

self:onSpeech("activate", function(self, speaker, fullText)
  speaker:echoAt("The trash compactor whirs as it activates.")
end)

room:onTime (hour, callback)

registers a function to run every time the hour changes to a certain value.

Parameters:

• hour integer the hour of day to trigger at, 0-23
• callback func the function to run, taking arguments: 1. this Room

Usage:

self:onTime(6, function(self)
  -- Do something at 6am every day
end)

room:randomPlayer ()

chooses a random player in the room and returns them.

Returns:

Character the randomly picked player character, or nil if there were no players

room:setAccessDoor (dir, keywords, accessCheck)

sets up a voice-activated locked door.
All optional arguments can be omitted or set to nil.
After the accessCheck, four additional strings can be given to control:
1. The message to show in the speaker's room when the door opens. (Optional, uses a default message if not set.)
2. The message to show in the speaker's room when the door closes. (Optional, uses a default message if not set.)
3. The message to show in the other room when the door opens. (Optional, uses the doorOpenMessage if not set.)
4. The message to show in the other room when the door closes. (Optional, uses the doorCloseMessage if not set.)

Parameters:

• dir string the name of the exit (n, north, etc)
• keywords string the list of words to trigger the door. (Optional, uses " access enter entry" if not set.)
• accessCheck function A function which determines whether a character can use the door. (Optional, use nil if not specifying.)

Usage:

• -- Set up a basic access door which works for everyone
  self:setAccessDoor("north")

• -- Set up an access door to the east which uses custom keywords
  self:setAccessDoor("east", "east letmein")

• -- Set up an access door to the north which uses default keywords but only allows
  -- characters with the "myArea.hasDoorAccess" variable set to true.
  self:setAccessDoor("north", nil, function(ch)
    if ch:getVar("myArea.hasDoorAccess") == true then
      -- You can use this opportunity to add any echoes you want.
      self:echo("&cThe door panel blinks green and chimes pleasantly.")
      return true
    else
      -- This function should handle any 'access denied' output appropriately.
      self:echo("&zThe door panel issues a loud warning: &RAccess Denied")
      return false
    end
  end)

• -- Set up an access door on the up exit using default keywords, no access check,
  -- but custom open/close messages
  self:setAccessDoor("up", nil, nil,
    "The manhole cover sides out of the way automatically.",
    "Grinding loudly, the manhole cover is replaced, blocking the way up.",
    "The manhole cover in the middle of the street spontaneously slides out of view!",
    "Just as quickly as it opened, the manhole cover slides closed again."
  )

room:setClanAccessDoor (dir, keywords, clanName)

sets up a voice-activated locked door which works for members of the given clan.
As with setAccessDoor, optional arguments can be sent after the keywords arg to control the messages:
1. The message to show to the speaker's room when access is granted. Empty string can be used to suppress. (Optional, uses a default if not set.)
2. The message to show to the speaker's room when access is denied. Empty string can be used to suppress. (Optional, uses a default if not set.)
3. The message to show in the speaker's room when the door opens. (Optional, uses a default message if not set.)
4. The message to show in the speaker's room when the door closes. (Optional, uses a default message if not set.)
5. The message to show in the other room when the door opens. (Optional, uses the doorOpenMessage if not set.)
6. The message to show in the other room when the door closes. (Optional, uses the doorCloseMessage if not set.)

Parameters:

• dir string the name of the exit (n, north, etc)
• keywords string the list of words to trigger the door. (Optional, uses " access enter entry" if not set.)
• clanName string the clan which the door works for

Usage:

• -- Set up a basic access door which works for everyone in the Galactic Empire
  self:setClanAccessDoor("north", nil, "The Galactic Empire")

• -- Set up a basic access door which works for everyone in the Galactic Empire, with custom messages
  self:setClanAccessDoor("north", nil, "The Galactic Empire",
    "", -- No happy message when it works. This is the Empire, after all.
    "&zA harsh voice barks out, \"&REntry is only permitted to Imperial personnel!&z\""
  )

room:setClanLeaderAccessDoor (dir, keywords, clanName)

sets up a voice-activated locked door which works for leader/first/second of the given clan.
As with setAccessDoor, optional arguments can be sent after the keywords arg to control the messages:
1. The message to show to the speaker's room when access is granted. Empty string can be used to suppress. (Optional, uses a default if not set.)
2. The message to show to the speaker's room when access is denied. Empty string can be used to suppress. (Optional, uses a default if not set.)
3. The message to show in the speaker's room when the door opens. (Optional, uses a default message if not set.)
4. The message to show in the speaker's room when the door closes. (Optional, uses a default message if not set.)
5. The message to show in the other room when the door opens. (Optional, uses the doorOpenMessage if not set.)
6. The message to show in the other room when the door closes. (Optional, uses the doorCloseMessage if not set.)

Parameters:

• dir string the name of the exit (n, north, etc)
• keywords string the list of words to trigger the door. (Optional, uses " access enter entry" if not set.)
• clanName string the clan which the door works for. Use "local" to check the current planet government.

Usage:

• -- Set up a basic access door which works for leaders in the Galactic Empire
  self:setClanLeaderAccessDoor("north", nil, "The Galactic Empire")

• -- Set up a basic access door which works for leaders in the Galactic Empire, with custom messages
  self:setClanLeaderAccessDoor("north", nil, "The Galactic Empire",
    "&zA speaker says, \"&GImperial vault access granted.&z\"",
    "&zA harsh voice barks out, \"&RVault access denied!&z\""
  )

room:setDescription (description)

set the description of a room.

Parameters:

• description string the new description

room:setFlag (flag, value)

set a flag on this room.

Parameters:

• flag string The flag to set
• value boolean The new value to set

Usage:

room:setFlag("silence", true)

room:setName (name)

set the name of a room.

Parameters:

• name string the new name

room:setTunnel (value)

set the room's tunnel value

Parameters:

• value integer the new tunnel value (0 to 32,767)

room:setVar (varName, value, ttl)

set a variable on a room

Parameters:

• varName string the name of the variable to set
• value the value, a string, number, or boolean. Pass in nil here to remove a variable.
• ttl number the number of seconds to keep the variable, in seconds. (optional, if not specified it's kept indefinitely)

room:ships ()

get an iterator over ships in the room

Returns:

an iterator of Ship

Usage:

for ship in room:ships() do
  -- do something
end