#People Mod

NOTE: Requires my fork of minetest to work properly. In particular:

• 740f057253
• 7b7e8bd4b9
• 8eb489ece1
• 8772041b43
• f5b73e0baa

This mod provides 'people' (non player characters) that are programmable in-game. Each NPC's Lua code runs inside a secure sandbox for that NPC only.

Author: Ciaran Gultnieks License: LGPL

Includes lua sandbox setup code from mesecons by Jeija (also LGPL), and inspiration from the npcf mod, and (obviously!) the mesecons lua controller design.

The character model is a modified version of the default player model from the default minetest game.

##Requirements

Optionally, you might want these mods:

• areas (my fork of it) - https://github.com/CiaranG/areas - for footpath navigation support
• moddebug - https://gitlab.com/CiaranG/moddebug - for debug logging

##Usage

To create a lua_npc, issue this command:

/people create Bob

This places a person called "Bob" at your current location.

Then, right-click the npc at any time to program it. For now, until I think of a better name, we'll refer to the code you enter here as "the person's lua code"!

##The Person's Lua Code

This code, as entered in the right-click dialog for a person you own, is really an event handler. It runs in a sandbox, and when called will always have a variable called 'event'. This is a table, and the "type" field determines the type of event that caused the call.

Here is a very simple example:

if event.type == "program" then action = {"follow", name="Ciaran"} end

When you enter this and hit the Program button, the person will start following the player called Ciaran and keep doing that until they log off. Because the code does nothing in response to an "act" event, at that point they will go into a permanent wait (sleep) state.

##Events

The following event types are received by the person's lua code:

###act

This happens when the person has no current action (see the Actions section). The handler should select a new action, by setting the 'action' variable. If it fails to do so, the person will do an automatic wait.

###tell

This happens when a player (who must be the owner, current) sends a message to the person. It can be used to respond to commands.

###step

This happens only when the "step" action is running. It's called every server step, with event.dtime containing the time since the last step. The handler should update the speed and yaw variables, or set a new action.

###program

This happens when the lua code has been edited.

###activate

This happens when the entity is activated (either it's brand new, or is in a block that was unloaded but is now loaded). It is called with event.dtime_s containing the time since it was last active.

###punched

This happens when a player punches the entity. The name of the offending player is sent as event.puncher.

##Actions

Actions are the basic building blocks of object behaviour. A person always has a current action which they are completing, the execution of which is handled by the mod. The job of the lua programming within the person is to sit at a higher level of 'conciousness' and select the appropriate actions.

The person's lua code receives an "act" event when it should select an action - usually when the current action completes. It can also set/replace the current action in response to any other event. Setting the action is a simple case of setting the 'action' variable within the lua code.

An action is defined by a table, where the first element [1] is the ID of the action, and additional named fields contain parameters. For a simple example, {"go", pos={5,0,5}} is an action to move the person to the given position.

###Action types

The following actions are currently defined:

####go, with pos={x,y,z} Walks to the given position.

####go, with name="string" Walks to a named position - names are looked up using the areas module, if present This converts to go, pos={x,y,z}, with name retained for reference.

####follow, with name="playername" Follows the given player indefinitely (or at least until they log off).

####face, with pos={x,y,z} Standing still, face towards the given position.

####wait, with time Do nothing for that many seconds. This may allow the entity to be deactivated and unloaded, in which case it will be reactivated at the appropriate time. Short waits may not result in deactivation.

####step Allow's the person's lua code to handle on_step itself. It will receive "step" events (with dtime) and should reset the action when it no longer needs to do this. It can update 'speed' and 'yaw' and these will be used.

###Nesting

Any action can have a "prevaction" field, which should be a valid action itself. It will be set when the action has completed. This can be used to nest actions.

The actions themselves may make use of this functionality. For example, the follow action is implemented by repeatedly selecting positions near the target player, and then replacing it self with a "go" action with the original follow nested as a "prevaction" within it. Thus, when the "go" completes, the follow resumes once more.

##Chat Commands

People can be managed and controlled via chat commands.

The following commands are available:

###/people help Lists all the available commands.

###/people create Creates a new person, at your current location.

###/people delete Deletes a person.

###/people where Tells you the current location of a person.

###/people summon Moves the person to your current location.

###/people setowner Changes the owner of the person.

###/people tell The person receives a "tell" event with the given message.

###/people status Lists all people in the word, and their current status (active/inactive).

###/people skin <skin_name|list> Sets the skin of the person to the named one. (Or use 'list' to get a list of available skins, which come from the skins mod).

##Autonomy and Activation

People are 'autonomous' - i.e. they will continue to act even when no player is nearby. Indeed, they will continue to act even when no player at all is logged in to the server.

However, they are designed to be able to not remain active unless necessary. This is mostly done by use of the "wait" action.

If you set a person to wait for 5 minutes, then assuming no player or other active entity is nearby, the block the person is in (and surrounding blocks) will be unloaded, and the person will cease to exist as far as the minetest engine is concerned. However, after 5 minutes, this mod will reactivate it by reloading the block.

###Force Loading This mod uses the 'force loading' API (which is silly and inadequate) to reactive sleeping entities when it needs to. It does not require the persistence over server restarts of force-loaded blocks, and while it ought to clean up any force loading it does almost immediately, that cannot happen if there is a server crash or other unclean shutdown at the wrong moment. You could mitigate this by always removing the force loaded blocks file from the world directory on startup.

Ultimately it won't use this 'feature' at all.