LOTJ Lua API

• Index

Contents

• Class Character
• Global functions

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 character

Functions for mobs and players

Class Character

Global functions

Class Character

character:act ()

Underlying "act" mechanic in the mud core

character:adjustForce (amount)

adjust a character's current force/mana.

Parameters:

• amount number of force to add. Negative amounts take it away.

Usage:

ch:echoAt("You feel a sudden burst of the force!")
ch:adjustForce(500)

character:adjustMove (amount)

adjust a character's current movement.

Parameters:

• amount number of movement to add. Negative amounts take it away.

Usage:

ch:echoAt("You get tired!")
ch:adjustMove(-100)

character:adjustSkill (skill, adjustment)

increase or decrease a player's percentage in a skill.

Parameters:

• skill string the name of the skill or force ability
• adjustment number the amount to adjust it by, -100 - 100

Usage:

ch:adjustSkill("kick", 2)

character:attack (target)

make this character attack another. Does nothing if the mob is already in combat.

Parameters:

• target Character the character to attack.

Returns:

boolean true if the attack was started successfully, false if not.

Usage:

ch:attack(otherPerson)

character:awardCredits (amount)

award (or fine) credits. If the number is negative, it will remove that many credits. If that would take the player below 0, the amount is adjusted to leave them with exactly 0. This function doesn't echo anything to the player on its own, so you may want to add an echoAt.

Parameters:

• amount number the number of credits to award or remove

Returns:

Character this character, for call chaining.

Usage:

• ch:echoAt("Good job! Here are 5000 credits.")
  ch:awardCredits(5000)

• ch:echoAt("Uh oh! The pirate takes a lot of your credits.")
  ch:awardCredits(-50000)

character:callBackup ()

call police backup

Returns:

boolean true if the call was successful, false if not.

character:callMob (vnum, rounds)

begin a countdown for calling a mob vnum as a follower. Returns false if the call failed. This happens if a call timer was already active for another mob.

Parameters:

• vnum number the mob vnum to call
• rounds number the number of rounds to wait before the mob appears

Returns:

boolean true if the call was started successfully, false if not.

Usage:

-- Load mob #40051 as a follower after waiting for 10 rounds
ch:callMob(40051, 10)

character:canSee (target)

whether this character can see the given object or character.

Parameters:

• target a Character or Object

Returns:

boolean true if the character can see the given thing, false otherwise

Usage:

if not self:canSee(ch) then
  self:force("say I can't see you!")
end

character:carrying (params)

get an iterator over objects in the character's inventory. Any objects they're wearing are ignored, as our items inside containers.

Parameters:

• params table (optional) a table to limit matches. In this case, only accepts "stacks" as the key and true/false as the value.

Returns:

an iterator of Object

Usage:

• for obj in ch:carrying() do
    -- do something
  end

• -- get the stacked objects in a character's inventory
  for obj in ch:carrying({ stacks = true }) do
    -- do something
  end

character:damage (amount, byCh)

damage a character.

Parameters:

• amount number of damage to do.
• byCh Character the character doing the damage, if applicable. Can be omitted or set to nil.

Usage:

ch:damage(1000)

character:drop (object)

drop an object from the character's inventory.

Parameters:

• object Object the object to drop

Usage:

ch:drop(something)

character:echo (message, args)

send a message to everyone in the character's room except for them.

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:

ch:echo("{1} lashes out violently with a tentacle, hitting {2} in the face!", ch, target)

character:echoAt (text)

display some text to the character.

Parameters:

• text string the message to show

Usage:

ch:echoAt("You hear a strange sound in the distance...")

character:echoAtLang (speaker, text, args)

display some text to the character while applying the speaker's language for speech.

Parameters:

• speaker Character the character speaking in this echo, for purposes of adding a language filter.
• text string the message to show
• args any any number of arguments corresponding to the {#} tokens in the message. {1} will refer to the first arg, etc.

Usage:

ch:echoAtLang(self, "Everything goes black as you lose consciousness. The last thing you remember is {1} saying \"Never underestimate the Hutts.\" over your body.", self)

character:echoLang (speaker, message, args)

send a message to everyone in the character's room except for them, using the speaker's language for speech.

Parameters:

• speaker Character the character speaking in this echo, for purposes of adding a language filter.
• 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:

ch:echoLang(self, "{1} chortles gleefully and says \"I am a glorious Hutt\" before hitting {2} in the face with his tail!", self, ch)

character:emote (text)

perform the given emote. Convenience alias for self:force("emote "..text)

Parameters:

• text string the action to emote

character:focus (target)

change the current target of a mob in combat. Does nothing if the mob is not in combat.

Parameters:

• target Character the character to switch focus to.

Usage:

ch:focus(otherPerson)

character:followers ()

get an iterator for the character's current followers.

Usage:

for follower in ch:followers() do
  follower:toRoom(somewhere)
end

character:force (command, account, totp)

make the character enter the given command.

Parameters:

• command string the command to run
• account account (optional) The account to use to elevate privileges of the force (to 103, or the top level of the account, whichever is less).
• totp string (optional, required with account) the totp code for the specified account. If not valid, the force will still happen just without elevated privileges.

Usage:

ch:force("say Hello there!")

character:gainExp (amount, ability, groupGain)

award experience to the player.

Parameters:

• amount number the amount of experience to award
• ability string the class name (bounty hunting, combat, etc)
• groupGain boolean whether to give the same experience to a leader main's group (optional, defaults to false)

Usage:

ch:gainExp(10000, "combat")

character:gainLevels (amount, ability)

award levels to the player.

Parameters:

• amount number the number of levels to award (1 to 149)
• ability string the class name (bounty hunting, combat, etc)

Usage:

ch:gainLevels(1, "combat")

character:getAIDescription ()

get the description of the character proided to gpt based AI systems as a prompt for the AI to use

Returns:

string the aidescription for this character

character:getAlignment ()

get the character's current alignment.

Returns:

integer the character's current alignment

character:getBio ()

get the full bio for a player character (what you see when looking at them).

Returns:

string the bio for this character

character:getBloodToxicity ()

get the character's current blood toxicity, 0 (good) - 100 (bad).

Returns:

number the character's blood toxicity

character:getCTime (time)

gets a full CTime stringification of a UNIX timestamp

Parameters:

• time number the UNIX timestamp

Returns:

string the stringified timestamp

Usage:

ch:getCTime(1711766514)
-- returns: Fri Mar 29, 2024 8:41:54 PM UTC -6

character:getCarryWeight ()

get the character's current carried weight.

Returns:

number the combined weight of all items the character is carrying

character:getCharisma ()

get the character's current charisma attribute.

Returns:

number the character's current charisma, including worn items and effects

character:getClan ()

get the character's current clan.

Returns:

Clan the character's current clan, or nil if they're not in one

character:getClanDivision ()

get the character's clan division ID and name.

Returns:

1. number the division number, or nil if not in a clan
2. string the division name, or nil if not in a clan

Usage:

local divNum, divName = ch:getClanDivision()

character:getClanRank ()

get the character's clan rank ID and name.

Returns:

1. number the rank number, or nil if not in a clan
2. string the rank name, or nil if not in a clan

Usage:

local rankNum, rankName = ch:getClanRank()

character:getConstitution ()

get the character's current constitution attribute.

Returns:

number the character's current constitution, including worn items and effects

character:getCredits ()

get the character's current carried credits.

Returns:

number the character's carried credit balance

character:getDescription ()

get the full description for a character (what you see when looking at them).

Returns:

string the description for this character

character:getDexterity ()

get the character's current dexterity attribute.

Returns:

number the character's current dexterity, including worn items and effects

character:getFighting ()

get the character this one is currently fighting.

Returns:

Character the character they're fighting, or nil if not fighting anyone

character:getFollowing ()

get the character this one is currently following.

Returns:

Character the character they're following, or nil if not following anyone

character:getForce ()

get the character's current force attribute.

Returns:

number the character's current force, including worn items and effects

character:getForceClass ()

get the character's current force class.

Returns:

number the character's current force class for players, or 0 for NPCs

character:getForceRank ()

get the character's current force rank.

Returns:

number the character's current force rank for players, or 0 for NPCs

character:getGName (looker)

get the greet name for a character.

Parameters:

• looker character (optional) The character looking at the target person.

Returns:

string the greet name of the target character

character:getHp ()

get the character's current hp.

Returns:

integer the character's current hp

character:getInArea ()

get the character's current area.

Returns:

Area the area

character:getInRoom ()

get the character's current room.

Returns:

Room the room

character:getInShip ()

getInShip

Returns:

Object the ship the character is in

character:getInstalledCyber (cyberType)

get whether a character has a given cyber type installed, and if so what rating it is.

Parameters:

• cyberType number the type of cybernetic to check for (see builder guide for cybernetic values)

Returns:

1. boolean true if cyber is installed, false otherwise
2. integer rating the class/rating of the installed cybernetic, if applicable (like the amount of strength bonus, etc) {"getInstalledCyber", lapichgetinstalled_cyber},

character:getIntelligence ()

get the character's current intelligence attribute.

Returns:

number the character's current intelligence, including worn items and effects

character:getLevel ()

get the character's level in the given class name.

Returns:

integer the character's level in this class

Usage:

if ch:getLevel("combat") >= 100 then
  -- do stuff
end

character:getLightsaberForm ()

get the character's lightsaber form.

Returns:

integer the character's lightsaber form (between 0 and 7)

character:getLongDescription ()

get the long description for a character (what you see when looking in the room).

Returns:

string the long description for this character

character:getLuck ()

get the character's current luck attribute.

Returns:

number the character's current luck, including worn items and effects

character:getMainAbility ()

get the character's main class name.

Returns:

the character's main class

Usage:

if ch:getMainAbility() == "bounty hunting" then
  -- do stuff
end

character:getMana ()

get the character's current mana.

Returns:

integer the character's current mana

character:getMaxClassLevel ()

get the character's maximum level in the given class name.

Returns:

integer the character's maximum level in this class

Usage:

if ch:getMaxClassLevel("force") > 1 then
  -- do stuff
end

character:getMaxHp ()

get the character's maximum hp.

Returns:

integer the character's maximum hp

character:getMaxMana ()

get the character's maximum mana.

Returns:

integer the character's maximum mana

character:getMaxMove ()

get the character's maximum movement.

Returns:

integer the character's maximum movement

character:getMentalState ()

get the character's current mental state, 0 (good) - 100 (bad).

Returns:

number the character's mental state

character:getMicroCTime (time)

gets a micro-CTime stringification of a UNIX timestamp

Parameters:

• time number the UNIX timestamp

Returns:

string the micro-stringified timestamp

Usage:

ch:getMicroCTime(1711766514)
-- returns: 03/29/24

character:getMiniCTime (time, true)

gets a mini-CTime stringification of a UNIX timestamp

Parameters:

• time number the UNIX timestamp
• true boolean if you want the string to include seconds, false if not.

Returns:

string the mini-stringified timestamp

Usage:

ch:getMiniCTime(1711766514, true)
-- returns: 03/29/24 8:41:54 PM

character:getMove ()

get the character's current movement.

Returns:

integer the character's current movement

character:getName ()

get the name (keywords) for a character.

Returns:

string the keyword(s) for this character

character:getNumAttacks ()

get the character's number of attacks

Returns:

integer the number of attacks

character:getPermCharisma ()

get the character's permanent charisma attribute.

Returns:

number the character's permanent charisma

character:getPermConstitution ()

get the character's permanent constitution attribute.

Returns:

number the character's permanent constitution

character:getPermDexterity ()

get the character's permanent dexterity attribute.

Returns:

number the character's permanent dexterity

character:getPermForce ()

get the character's permanent force attribute.

Returns:

number the character's permanent force

character:getPermIntelligence ()

get the character's permanent intelligence attribute.

Returns:

number the character's permanent intelligence

character:getPermLuck ()

get the character's permanent luck attribute.

Returns:

number the character's permanent luck

character:getPermStrength ()

get the character's permanent strength attribute.

Returns:

number the character's permanent strength

character:getPermWisdom ()

get the character's current permanent attribute.

Returns:

number the character's permanent wisdom

character:getPlrHome ()

get the player's home

Returns:

room the player's home room

Usage:

ch:getPlrHome()

character:getPosition ()

get the character's position

Returns:

string the character's position

character:getRace ()

get the character's race. Note that return values will be uppercased as shown in showrace. Sees through disguises.

Returns:

the character's race name

Usage:

if ch:getRace() == "Corellian" then
  -- do stuff
end

character:getSex ()

get the sex of a character.

Returns:

string the sex string (male, female, or neutral)

character:getShortDescription ()

get the short description for a character.

Returns:

string the short description for this character

character:getSkill ()

get the character's percentage in a given skill.

Returns:

integer the character's percent in this skill, or 0 if they don't know it

Usage:

if ch:getSkill("dodge") >= 50 then
  -- do stuff
end

character:getStrength ()

get the character's current strength attribute.

Returns:

number the character's current strength, including worn items and effects

character:getSwitched ()

get the inverse character if switched (e.g., returns the PC controlled if used on a possessed NPC).

Returns:

Character the character, or nil if not found (or not switched)

Usage:

ch:getSwitched()

character:getTerminal ()

gets the terminal in the same room as the char

Returns:

terminal the Terminal, or nil if there is none

character:getTimezone ()

gets the integer timezone value for a character (defaults to UTC +0 for NPCs)

Returns:

integer the timezone value

character:getVNum ()

return the mob's vnum

Returns:

integer the mob's vnum, or -1 if it's a player

character:getVar (varName, default)

get a character'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.

Usage:

• if ch:getVar("wroona.onQuest") then
    -- do stuff
  end

• ch:echoAt("I have met you "..ch:getVar("wroona.timesMetMob", 1).." times.")

character:getVarTimer (varName)

get the remaining time on a character'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.

Usage:

• if ch:getVarTimer("wroona.onQuest") > 10 then
    -- do stuff
  end

• ch:echoAt("You have "..ch:getVarTimer("wroona.timesMetMob").." seconds left.")

character:getVisibleRace ()

get the character's race, or what they're disguised as. Note that return values will be uppercased as shown in showrace.

Returns:

the race which the character currently appears as

Usage:

if ch:getVisibleRace() == "Corellian" then
  -- do stuff
end

character:getWasInRoom ()

get the character's previous room.

Returns:

Room the room

character:getWisdom ()

get the character's current wisdom attribute.

Returns:

number the character's current wisdom, including worn items and effects

character:hasActFlag (flag)

get whether an act flag is set on this character.

Parameters:

• flag string The flag to check for

Returns:

boolean True if the flag is set, false otherwise

Usage:

if ch:hasActFlag("sentinel") do
  ch:echoAt("You don't feel like walking.")
end

character:hasAffect (the)

checks if the character has an affect

Parameters:

• the string affect to look for

Returns:

boolean true if the char has the affect, false if not

character:hasAttack (the)

checks if the character has an attack

Parameters:

• the string attack to look for

Returns:

boolean true if the char has the attack, false if not

character:hasBestowment (bestowment)

get whether a player has a given bestowment/empowerment

Parameters:

• bestowment string the bestowment/empowerment to check for

Returns:

boolean true if the player has that bestowment, false otherwise

character:hasDefense (the)

checks if the character has a defense

Parameters:

• the string defense to look for

Returns:

boolean true if the char has the defense, false if not

character:hasEncryptedHistory ()

whether this player has an encrypted history

Returns:

bool true if the player has an encrypted history, false otherwise

character:hasImmune (the)

checks if the character has an immunity

Parameters:

• the string immunity to look for

Returns:

boolean true if the char has the immunity, false if not

character:hasPlrFlag (flag)

get whether a player flag is set on this character.

Parameters:

• flag string The flag to check for

Returns:

boolean True if the flag is set, false otherwise

Usage:

if ch:hasPlrFlag("autoexits") do
  ch:echoAt("You just saw the exits.")
end

character:hasResistant (the)

checks if the character has a resistance

Parameters:

• the string resistance to look for

Returns:

boolean true if the char has the resistance, false if not

character:hasSusceptible (the)

checks if the character has a susceptibility

Parameters:

• the string susceptibility to look for

Returns:

boolean true if the char has the susceptibility, false if not

character:heal (amount)

heal a character.

Parameters:

• amount number of hp to restore.

Usage:

ch:heal(1000)

character:interrupt ()

interrupt any timed action the character is doing.

Usage:

self:onAct("begins drawing a bead on you!", function(self, ch)
  self:emote("hides behind a rock!")
  ch:interrupt()
end)

character:isAFK ()

whether this player is AFK.

Returns:

bool true if the player is AFK, false otherwise

character:isAffected (effectName)

whether this character is affected by the given effect name.

Parameters:

• effectName string the name of the effect to check for.

Returns:

boolean true if the character is affected by it, false otherwise.

Usage:

if ch:isAffected("sneak") then
  self:force("say I didn't see you come in!")
end

character:isBotting ()

whether this player is botting.

Returns:

bool true if the player is botting, false otherwise

character:isCitizen ()

checks if the character is a citizen mob

Returns:

boolean true if the char is a citizen mob, false if not

character:isCriminal ()

checks if the character is a criminal mob

Returns:

boolean true if the char is a criminal mob, false if not

character:isDroid ()

whether this character is a droid.

Returns:

boolean true if the character is a droid, false otherwise

Usage:

if not ch:isDroid() then
  ch:echoAt("You're a droid, beep boop!")
end

character:isFighting ()

whether this character is fighting.

Returns:

bool true if the character is fighting, false otherwise

character:isImmortal ()

whether this character is an immortal (RPC or higher).

Returns:

bool true if the character is an immortal.

character:isJailed ()

whether this character is presently jailed.

Returns:

boolean true if the character is in jail, false otherwise.

Usage:

if ch:isJailed() then
  ch:echoAt("You're currently in jail.")
end

character:isNPC ()

whether this character is an NPC.

Returns:

boolean true if the character is an NPC, false if they're a player

Usage:

if not ch:isNPC() then
  ch:echoAt("You're a player!")
end

character:isPC ()

whether this character is a player.

Returns:

bool true if the character is a player, false otherwise

character:isPolice ()

checks if the character is a police mob

Returns:

boolean true if the char is a police mob, false if not

character:isValid ()

isValid

Returns:

boolean true if the character is valid, false if not

character:restore ()

restore a character.

Usage:

ch:restore()

character:say (text)

say some text. Convenience alias for self:force("say "..text)

Parameters:

• text string the text to speak

character:sayTo (target, text)

say some text to a target. Convenience alias for self:force("sayto \""..target:getName().."\"" "..text)

Parameters:

• target Character the person to speak to
• text string the text to speak

character:setAIDescription (desc)

set the description of the character provided to gpt based AI systems as a prompt for the AI to use

Parameters:

• desc string the new aidescription

character:setActFlag (flag, value)

set a flag on this character.

Parameters:

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

Usage:

ch:setActFlag("deadly", true)

character:setAffect (the, to)

sets an affect for a character

Parameters:

• the string affect to set
• to boolean enable or disable the affect

Returns:

Character this character, for call chaining.

character:setAlignment (alignment)

set the character's current alignment, -1000 (evil) - 1000 (good).

Parameters:

• alignment integer the new alignment

Returns:

Character this character, for call chaining.

character:setAllSkills (val)

set a character's skill percentage for all knowable skills

Parameters:

• val integer the new value (between 0 and 100)

Returns:

Character this character, for call chaining.

character:setAttack (the, to)

sets an attack for a character

Parameters:

• the string attack to set
• to boolean enable or disable the attack

Returns:

Character this character, for call chaining.

character:setBio (bio)

set the full bio for a PC.

Parameters:

• bio string the new bio

character:setBloodToxicity (bloodToxicity)

set the character's current mental state, 0 (good) - 100 (bad).

Parameters:

• bloodToxicity number the new blood toxicity

Returns:

Character this character, for call chaining.

character:setClan (clan)

set the character's current clan

Parameters:

• clan Clan the clan to set the character to

Returns:

Character this character, for call chaining.

character:setClanDiv (the)

set the character's current clan division

Parameters:

• the int division number

Returns:

Character this character, for call chaining.

character:setClanRank (the)

set the character's current clan rank

Parameters:

• the int rank number

Returns:

Character this character, for call chaining.

character:setCredits (credits)

set the credits on this NPC.

Parameters:

• credits number the amount of credits

Returns:

Character this character, for call chaining.

Usage:

ch:setCredits(275000)

character:setDefense (the, to)

sets a defense for a character

Parameters:

• the string defense to set
• to boolean enable or disable the defense

Returns:

Character this character, for call chaining.

character:setDescription (desc)

set the full description for an NPC (what you see when looking at them).

Parameters:

• desc string the new description

character:setForceClass (class)

set the character's current force class, 0 - 8

Parameters:

• class integer the new class

Returns:

Character this character, for call chaining.

character:setForceRank (rank)

set the character's current force rank, 0 - 3

Parameters:

• rank integer the new rank

Returns:

Character this character, for call chaining.

character:setImmune (the, to)

sets an immunity for a character

Parameters:

• the string immunity to set
• to boolean enable or disable the immunity

Returns:

Character this character, for call chaining.

character:setInstalledCyber (cyberType, installed, the)

set whether a character has a given cyber type installed.

Parameters:

• cyberType number the type of cybernetic to check for (see builder guide for cybernetic values)
• installed boolean whether they should have the cybernetic installed. true = install, false = uninstall
• the number class/rating of the cybernetic, if installing and applicable (for cybernetics with a variable effect like str, hp) {"setInstalledCyber", lapichsetinstalled_cyber},

character:setJailed (the)

set the date/time the character was jailed.

Parameters:

• the integer date/time the character was jailed, or 0 if the character is no longer in jail.

Returns:

Character this character, for call chaining.

character:setLevel (the, ability)

sets a player's ability class level.

Parameters:

• the number level to set (1 to 150)
• ability string the class name (bounty hunting, combat, etc)

Usage:

ch:setLevel(150, "combat")

character:setLightsaberForm (the)

sets the character's lightsaber form.

Parameters:

• the integer new value (between 0 and 7)

Returns:

Character this character, for call chaining.

character:setLongDescription (desc)

set the long description for an NPC (what you see when looking in the room).

Parameters:

• desc string the new long description

Usage:

ch:setLongDescription("An angry pirate captain stands here drinking ale.")

character:setMainAbility (the)

sets the character's main ability class

Parameters:

• the string new ability class

Returns:

Character this character, for call chaining.

character:setMaxHp (the)

sets the character's maximum hp.

Parameters:

• the integer new value (between 1 and 1,000,000)

Returns:

Character this character, for call chaining.

character:setMaxMana (the)

sets the character's maximum mana.

Parameters:

• the integer new value (between 1 and 1,000,000)

Returns:

Character this character, for call chaining.

character:setMaxMove (the)

sets the character's maximum movement.

Parameters:

• the integer new value (between 1 and 1,000,000)

Returns:

Character this character, for call chaining.

character:setMentalState (mentalState)

set the character's current mental state, 0 (good) - 100 (bad).

Parameters:

• mentalState integer the new mental state

Returns:

Character this character, for call chaining.

character:setName (desc)

set the name (keywords) for a character.

Parameters:

• desc string the new name (keywords)

Usage:

ch:setName("pirate captain angry")

character:setNumAttacks (the)

sets the character's number of attacks

Parameters:

• the integer new value (between 0 and 20)

Returns:

Character this character, for call chaining.

character:setPermCharisma (the)

sets the character's permanent charisma attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermConstitution (the)

sets the character's permanent constitution attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermDexterity (the)

sets the character's permanent dexterity attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermForce (the)

sets the character's permanent force attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermIntelligence (the)

sets the character's permanent intelligence attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermLuck (the)

sets the character's permanent luck attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermStrength (the)

sets the character's permanent strength attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPermWisdom (the)

sets the character's permanent wisdom attribute.

Parameters:

• the integer new value (between 1 and 25)

Returns:

Character this character, for call chaining.

character:setPosition (the)

sets the character's position

Parameters:

• the string new position

Returns:

Character this character, for call chaining.

character:setRace (the)

sets the character's race

Parameters:

• the string new race

Returns:

Character this character, for call chaining.

character:setResistant (the, to)

sets a resistance for a character

Parameters:

• the string resistance to set
• to boolean enable or disable the resistance

Returns:

Character this character, for call chaining.

character:setSex (sex)

set the sex for an NPC.

Parameters:

• sex string the new sex (male, female, or neutral)

Usage:

ch:setSex("female")

character:setShortDescription (desc)

set the short description for an NPC.

Parameters:

• desc string the new short description

Usage:

ch:setShortDescription("an angry pirate captain")

character:setSkill (skill, val)

set a character's skill percentage

Parameters:

• skill string the skill name
• val integer the new value (between 0 and 100)

Returns:

Character this character, for call chaining.

character:setSusceptible (the, to)

sets a susceptibility for a character

Parameters:

• the string susceptibility to set
• to boolean enable or disable the susceptibility

Returns:

Character this character, for call chaining.

character:setTopLevel (level)

set the top level on this NPC.

Parameters:

• level number the level to set

Returns:

Character this character, for call chaining.

Usage:

ch:setTopLevel(100)

character:setVar (varName, value, ttl)

set a variable on a character

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)

Usage:

• -- remove the wroona.onQuest variable
  ch:setVar("wroona.onQuest", nil)

• -- set the wroona.didQuest variable and keep it for 24 hours
  ch:setVar("wroona.didQuest", true, 24*60*60)

character:slay (byCh)

instantly kill a character. (Or hospitalize them, if eligible)

Parameters:

• byCh Character the character doing the slaying, if applicable. Can be omitted or set to nil.

Usage:

ch:slay(dragonMob)

character:startFearing (target)

start fearing

Parameters:

• target Character the character to fear.

Usage:

ch:startFearing(otherPerson)

character:startHating (target)

start hating

Parameters:

• target Character the character to hate.

Usage:

ch:startHating(otherPerson)

character:startHunting (target)

start hunting

Parameters:

• target Character the character to hunt.

Usage:

ch:startHunting(otherPerson)

character:startTracking (target)

start tracking

Parameters:

• target Character the character to track.

Usage:

ch:startTracking(otherPerson)

character:stopFearing ()

stop fearing

Usage:

ch:stopFearing()

character:stopFighting (optional)

make this npc stop fighting

Parameters:

• optional ) boolean, stop both the character and their target from fighting

Usage:

ch:stopFighting()

character:stopHating ()

stop hating

Usage:

ch:stopHating()

character:stopHunting ()

stop hunting

Usage:

ch:stopHunting()

character:stopTracking ()

stop tracking

Usage:

ch:stopTracking()

character:stun (seconds)

stun (lag) a player for a given number of seconds. Stuns can overlap, but do not stack, so if you apply a 5-second stun on top of a 10-second stun, they will still only be stunned for 10 seconds.

Parameters:

• seconds integer the number of seconds to stun this character for.

Usage:

-- Lag for 5 seconds
ch:stun(5)

character:toRoom (room)

transfer the character to the given room. This does not show the character the room contents, so you may wish to ch:force("look") afterward.

Parameters:

• room the room to send them to, either a Room object or vnum

Usage:

ch:toRoom(12345)
ch:force("look")

character:wearing ()

get an iterator over objects the character is wearing.

Returns:

an iterator of Object

Usage:

for obj in ch:wearing() do
  -- do something
end

character:whenJailed ()

the date/time the character was jailed

Returns:

integer the time the character was jailed, or 0 if the character isn't in jail.

character:wornOnLocation (wearflag)

get a list of objects worn on a given location

Parameters:

• wearflag string of the location to check

Returns:

table a list of objects worn on the given location

Usage:

wornOnLocation("head")

Global functions

Character.connected ()

get an iterator over all connected players.

Returns:

an iterator of Character

Usage:

-- Move all players to room 10
local room = Room.getFromVNum(10)
for ch in Character.connected() do
  ch:toRoom(room)
  ch:echoAt("You've been transferred!")
end

Character.getFromName (name)

get any character in the world by name.

Parameters:

• name string the mob name

Returns:

Character the character, or nil if not found

Usage:

-- Find player "Puff"
local puff = Character.getFromName("Puff")
if not puff then
  LOTJ.log("Couldn't find Puff.")
end

Character.invoke (vnum)

create an instance of a mob.

Parameters:

• vnum number the mob vnum

Returns:

Character the new character

Usage:

• -- invoke mob 10000 and put it in a room
  Character.invoke(10000):toRoom(someRoom)

• -- invoke mob 1234 and do a few things with it
  local newCh = Character.invoke(1234)
  newCh:toRoom(someRoom)
  newCh:say("Hello, I'm here!")