NpcParse.lua

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. This property

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 an 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

Developers of LunaLua libraries that utilize the NPC message text (such as cinematX and customlotus) are strongly encouraged to update their APIs with an alternate setting that loads the necessary data from <pnpcRef>.data.<libraryname>; this ensures standardized compatibility between such libraries through npcParse.

It is also recommended to store newMsg strings and other complex strings 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.