LOTJ Lua API

• Index

Contents

• Class ObjProto

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 obj_proto

Functions for object prototypes, including triggers

Class ObjProto

Class ObjProto

objproto:onAct (message, callback)

registers a function to run when the given action message is shown in the object's room. Only applies to objects on the ground in the room, not anything in character inventories.

Parameters:

• message string the message to trigger on
• callback func the function to run, taking arguments: 1. this Object 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)

objproto:onCommand (command, callback)

registers a function to run when a character (player or NPC) enters a custom command. Works on any objects in the room or in the character's inventory (including equipped items). Does not work for objects in a container.

Parameters:

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

Usage:

self:onCommand("repair", function(self, ch, argument)
  ch:echoAt("You repaired "..self:getShortDescription()..".")
end)

objproto:onDamage (callback)

registers a function to run after an object gets damaged. This function runs before the object is potentially reduced to scraps. For objects tracking durability as a value, you can modify that durability here to prevent it from being destroyed. Other object types just have a random chance to break, and you can't prevent that here.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who is wearing the object (will be nil if it's on the ground)

Usage:

self:onDamage(function(self, ch)
  ch:echoAt(self:getShortDescription().." emits a sad noise.")
end)

objproto:onDrop (callback)

registers a function to run after a character drops this object.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who dropped the object

Usage:

self:onDrop(function(self, ch)
  ch:echoAt(self:getShortDescription().." falls to the ground with a loud clunk.")
end)

objproto:onExamine (callback)

registers a function to run after a character examines this object. This covers both look <thing> and examine <thing>.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who examined the object

Usage:

self:onExamine(function(self, ch)
  ch:echoAt("You notice bright red button on the underside of the device.")
end)

objproto:onGet (room, callback)

registers a function to run after a character gets this object from the room.

Parameters:

• room an optional flag to only trigger if the object is gotten from the room (as opposed to a container)
• callback func the function to run, taking arguments: 1. this Object 2. the Character who picked up the object

Usage:

self:onGet(function(self, ch)
  ch:echoAt("You carefully scoop up the pile of powder.")
end)

objproto:onGreet (callback)

registers a function to run when a character enters the room. Only works for objects on the ground.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who entered

Usage:

self:onGreet(function(self, target)
  target:echoAt("You notice "..self:getShortDescription().." blinking red.")
end)

objproto:onPull (callback)

registers a function to run after a button object is pulled.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who pulled it

Usage:

self:onPull(function(self, ch)
  ch:echoAt(self:getShortDescription().." does something because you pulled it.")
end)

objproto:onPush (callback)

registers a function to run after a button object is pushed.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who pushed it

Usage:

self:onPush(function(self, ch)
  ch:echoAt(self:getShortDescription().." does something because you pushed it.")
end)

objproto: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 Object

Usage:

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

objproto:onRemove (callback)

registers a function to run after a character unequips this object.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who removed the object

Usage:

self:onRemove(function(self, ch)
  ch:emote("makes a controlled descent and removes their jetpack.")
end)

objproto:onSpeech (message, callback)

registers a function to run when the given text is spoken in the room. Works for objects on the ground or in the direct inventory/equip of any characters in the room.

Parameters:

• message string the message to trigger on
• callback func the function to run, taking arguments: 1. this Object 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)

objproto: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 Object

Usage:

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

objproto:onUse (callback)

registers a function to run after an object is used. Setting an onUse allows the use command on any object regardless of its type. When an onUse happens, the default messages about using the object are suppressed, although the default behavior still kicks in (toggling lights, etc). For objects of type device, the object can be used with a target. This can be a character or object accessible to the player, and if present, either of these arguments will be passed to the onUse function. For consumable objects (food, drink, and cybernetics) the onUse prog is triggered when the object is consumed.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who used it 3. the Character targeted by the use command, for devices 4. the Object targeted by the use command, for devices

Usage:

• self:onUse(function(self, ch)
    ch:echoAt(self:getShortDescription().." does something because you used it.")
  end)

• self:onUse(function(self, ch, targetCh, targetObj)
    if not targetCh then
      ch:echoAt("This can only be used on a character.")
      return
    end
    targetCh:echoAt("You feel a surge of static electricity.")
    targetCh:echoAround("$n's hair sticks out in every direction.")
  end)

objproto:onWear (callback)

registers a function to run after a character equips this object.

Parameters:

• callback func the function to run, taking arguments: 1. this Object 2. the Character who wore the object

Usage:

self:onWear(function(self, ch)
  ch:emote("loosely straps "..self:getShortDescription().." over their shoulder.")
end)