NpcParse.lua

Attention: This page contains dead links!

Download

npcParse.lua is a library designed to provide a standardized method of storing shared data in an NPC's message text.

Installation

Install pnpc.lua by following the instructions on that library's page, then place the file npcParse.lua into the LuaScriptsLib folder.

How to Use

Basic Setup

To enable the npcParse library for a specific level, add this line to lunadll.lua:

local npcParse = API.load("npcParse");

It is also recommended to create a JSON file named npcdata.json in the level's resource folder.

How it Works

At runtime, npcParse will read lua tables stored in NPCs' message text and copy their information to the data tables of the respective pNPC references so that libraries can access them through <pnpcRef>.data.<section>, <pnpcRef>.data.<section>.<subsection>, <pnpcRef>.data.<section>.<subsection>.<sub-subsection> and so on. NPCs without correctly-formatted tables will be ignored. npcParse utilizes the following (optional) keys for additional functionality:

Name	Type	Default Value	Description
id	string	nil	If specified in the message table, npcParse will attempt to copy the corresponding data from npcdata.json into the NPC's pnpc data.
newMsg	string	""	If specified in either the message table or the JSON data, this string will replace the NPC's message table after it has been parsed. If left undefined, the message will be cleared so that the NPC cannot be spoken to.

npcParse also uses two special keys in npcdata.json: if a section labeled "_ALL" is defined, every NPC will be given the data in that section. If a section labeled "_ID" is defined, every NPC with a valid id key will receive that data. Data defined in user-named keys overrides the same properties in "_ID", and data in "_ID" overrides data in "_ALL".

Example

-- Sample NPC messages
{id='boss'}
{id='minion', quack=true}


-- Sample npcdata.json content
{
  "_ALL":
  {
    "customlotus": 
    {
      "bullets": 2
    }
  },

  "boss": 
  {
    "newMsg": "THIS IS A REPLACEMENT MESSAGE, YO.",
    "particles": 
    {
      "name": "robert"
    },
    "cinematX": 
    {
      "key": "steve",
      "icon": 1
    },
    "customlotus": 
    {
      "bullets": 999
    }
  },
	
  "minion": 
  {
    "cinematX": 
    {
      "key": "ian"
    },
    "npcGfx":
    {},
    "butts":
    {
      "dorkatron": "rockythechao"
    }
  }
}

NPCs with the first sample message will display the message "THIS IS A REPLACEMENT MESSAGE, YO." when spoken to and have all of the data in the "boss" table of the JSON file (e.g. <pnpcRef>.data.particles.name, etc.) NPCs with the second sample message cannot be spoken to (because newMsg is not defined) and will have the data in the "minion" table of the JSON file (<pnpcRef>.data.npcGfx, etc.) as well as the extra property quack (<pnpcRef>.data.quack). Every single NPC will have <pnpcRef>.data.customlotus.bullets, but NPCs with the boss ID will have a value of 999 stored there whereas every other NPC will have 2 instead.

Important Notes

For helper library devs

Developers of LunaLua libraries that utilize the NPC message text (such as customlotus and new NPCs) are strongly encouraged to design their APIs to load the necessary data from <pnpcRef>.data.<libraryname>; this ensures standardized compatibility between such libraries through npcParse.

Strings

It's generally safer to store newMsg strings and other complex string values in the npcdata.json file instead of directly in the message table as the SMBX editor may convert double quotation marks in NPC text into apostrophes. A possible alternative for the newMsg strings would be to give each applicable NPC a unique replacement string and check for that as a secondary id within the onMessageBox event, like so:

-- Sample NPC messages
{newMsg='talk_david'}
{newMsg='talk_norman'}


-- Sample lua code
function onMessageBox (eventObj, message)
    eventObj.cancelled = true
    
    if  message = "talk_david"  then
        Text.showMessageBox("Hi, I'm David!  Hoo-whee, look at me go!")
    
    elseif  message = "talk_norman"  then
        Text.showMessageBox("Hello, fellow human, I am a normal Earthling much like yourself.  Would you like to engage in perfectly mundane Earth activities such as consuming produce and battling Pikmin, or as our human youth prefers to call it, 'mining the crafts'?")    
    
    else
        eventObj.cancelled = false
    end
end