NPC (class)

This is the archived page of the old LunaLua documentation The rest of LunaLua related articles in this wiki contain a lot of outdated documentation preserved for historical purposes and may be used with legacy versions of the LunaLua. Please visit the SMBX2 Documentation Page to access the latest documentation for the LunaLua scripting system of the SMBX2 Project. Adding LunaLua contents into this Wiki is not advised.

This class provides fields/functions for managing NPCs in the current level. If you are saving this class into a variable/field, make sure you check that it is valid by using the field "isValid" before using it!

Static functions

Static NPC Functions
Function	Return values	Description
NPC.count()	number	How many NPCs are in the level.
NPC.get()	table of NPC	Returns all NPCs
NPC.get(number or table ids, int or table sections)	table of NPC	Returns all NPC with the matching ids and section-numbers (0-20). Use -1 for ids or sections if you want to ignore this filter. Only the NPCs with the same id and sections given by ids and sections will be returned. v0.7 has a critical bug crashing on this function! Be sure to be updated to 0.7.0.1!
NPC.getIntersecting(number x1, number y1, number x2, number y2)	table of NPC	Returns all NPCs which are intersecting with an area from x1/y1 to x2/y2.
NPC.iterateIntersecting(number x1, number y1, number x2, number y2)	function, table, number	Used to iterate through all NPCs intersecting with an area from x1/y1 to x2/y2. Returns an iterator function, a table of args and the iterator index. Use it like shown: for k,v in NPC.iterateIntersecting() do
NPC.spawn(number npcId, number x, number y, int sectionNumber)	NPC	Spawns a new npc. Note that sectionNumber is from 0-20 (-> Section 1 would be Section 0)
NPC.spawn(number npcId, number x, number y, int sectionNumber, boolean respawn)	NPC	Spawns a new npc. Note that sectionNumber is from 0-20 (-> Section 1 would be Section 0
NPC.spawn(number npcId, number x, number y, int sectionNumber, boolean respawn, boolean centered)	NPC	Spawns a new npc. Note that sectionNumber is from 0-20 (-> Section 1 would be Section 0. If centered is true then x and y are the middle position of the spawning npc.)
NPC(number index)	NPC	Returns the NPC object at position index in the global NPC table. (Invalid NPCs may be returned when using a strange index.)

Instance functions

These fields and functions are part of NPC Objects and have to be called for that object. Trying to call them from the static NPC class will result in an error. Example (feel free to copy it into your lua file to see how it works):

function onTick()
    for index,myNPC in ipairs(NPC.get()) do
        myNPC.speedY = -4
    end
end

NPC class
Type	Function/Field	Return values/Value type	Description
Function	NPC:mem(int offset, int fieldtype, object value)	nil	Sets a value of the NPC struct at a specific address-offset.
Function	NPC:mem(int offset, int fieldtype)	object	Returns a value of the NPC struct at a specific address-offset.
Function	NPC:kill()	nil	Kills the npc with the standard kill animation.
Function	NPC:kill(int killAnimation)	nil	Kills the npc with a specified animation, acting as if killAnimation was the harm type (see below).
Function	NPC:harm()	nil	Harms the npc as if it were hit by a thrown npc. (LunaLua ≥ v0.7.3)
Function	NPC:harm(int harmType)	nil	Harms the npc as if it took a certain type of damage. See constants for the different harm types. Note: Harm types with "EXT" in the name only work for this function. (LunaLua ≥ v0.7.3)
Function	NPC:harm(int harmType, int damage)	nil	Deals the given amount of damage to an NPC with the given harm type. The damage value is ignored by one-hit npcs. (LunaLua ≥ v0.7.3)
Function	NPC:toIce()	nil	Freezes a npc and transform it into ice. (LunaLua ≥ v0.7.2.1)
Function	NPC:toCoin()	nil	Transforms the npc into the coin effect. (Similar to Misc.npcToCoins(), just per NPC) (LunaLua ≥ v0.7.2.1)
Field	NPC.x	double	The x coordinate of the npc.
Field	NPC.y	double	The y coordinate of the npc.
Field	NPC.width	int	The width of the npc.
Field	NPC.height	int	The height of the npc.
Field	NPC.speedX	double	The x-speed of the npc.
Field	NPC.speedY	double	The y-speed of the npc.
Field	NPC.id	int	The npc-id of the npc.
Field (ro)	NPC.idx	number	The NPC index.
Field (ro)	NPC.uid		The unique ID of the npc.
Field (ro)	NPC.pid		The persistence identifier for this NPC. If the uid is less than 0x8000, it is guaranteed to be the same as pid. Intended for debugging.
Field (ro)	NPC.pidIsDirty		Flag to indicate that the persistence identifier is recycled. Intended for debugging.
Field	NPC.direction	int	The direction of the npc. NOTE: Setting the direction of a npc, resets the momentum of the npc. You can modify the speedX value if you want to set your own momentum.
Field	NPC.msg	VBStr	The message of the npc.
Field (ro)	NPC.attachedLayerName	VBStr	The attached layer.
Field (ro)	NPC.activateEventName	VBStr	The event name of the activate-event.
Field (ro)	NPC.deathEventName	VBStr	The event name of the death-event.
Field (ro)	NPC.noMoreObjInLayer	VBStr	The event name of the "No more objects in layer"-event.
Field (ro)	NPC.talkEventName	VBStr	The event name of the talk-event.
Field (ro)	NPC.layerName	VBStr	The layer name of the npc.
Field (ro)	NPC.layerObj	Layer	The layer object of the npc.
Field (ro)	NPC.attachedLayerObj	Layer	The attached layer object.
Field	NPC.ai1	number	The 1. AI-field. This field controls the behavouir of NPCs. Read more about it at: SMBX NPC AI (LunaLua ≥ v0.7.2)
Field	NPC.ai2	number	The 2. AI-field. This field controls the behavouir of NPCs. Read more about it at: SMBX NPC AI (LunaLua ≥ v0.7.2)
Field	NPC.ai3	number	The 3. AI-field. This field controls the behavouir of NPCs. Read more about it at: SMBX NPC AI (LunaLua ≥ v0.7.2)
Field	NPC.ai4	number	The 4. AI-field. This field controls the behavouir of NPCs. Read more about it at: SMBX NPC AI (LunaLua ≥ v0.7.2)
Field	NPC.ai5	number	The 5. AI-field. This field controls the behavouir of NPCs. Read more about it at: SMBX NPC AI (LunaLua ≥ v0.7.2)
Field	NPC.data		Data table for an NPC. It's necessary for npc-x.lua files, to be replaced by ai1 to ai5.
Field	NPC.drawOnlyMask	boolean	If only the mask of the NPC should be drawn. May not work if the sprite uses PNG. (LunaLua ≥ v0.7.2.1)
Field	NPC.invincibleToSword	boolean	If the NPC is invincible to Link's sword. (LunaLua ≥ v0.7.2.1)
Field	NPC.legacyBoss	boolean	If the NPC is a legacy boss. (LunaLua ≥ v0.7.2.1)
Field	NPC.friendly	boolean	If the NPC is friendly. (LunaLua ≥ v0.7.2.1)
Field	NPC.dontMove	boolean	If the NPC doesn't move. (LunaLua ≥ v0.7.2.1)
Field	NPC.collidesBlockBottom	boolean	If the NPC collides with a block on the bottom side. (LunaLua ≥ v0.7.2.2)
Field	NPC.collidesBlockLeft	boolean	If the NPC collides with a block on the left side. (LunaLua ≥ v0.7.2.2)
Field	NPC.collidesBlockUp	boolean	If the NPC collides with a block on the up side. (LunaLua ≥ v0.7.2.2)
Field	NPC.collidesBlockRight	boolean	If the NPC collides with a block on the right side. (LunaLua ≥ v0.7.2.2)
Field	NPC.underwater	boolean	If the NPC is underwater. (LunaLua ≥ v0.7.2.2)
Field	NPC.animationFrame	number	The current frame of the NPC. Can make NPC hidden by setting this value to -1. (LunaLua ≥ v0.7.2.2)
Field	NPC.animationTimer	number	The animation timer. If the timer reaches a specific value, then the animation frame of the NPC changes. (LunaLua ≥ v0.7.2.2)
Field (ro)	NPC.isValid	boolean	Checks if the NPC is acutally valid. Should always be used when storing this class into a variable/field.

Offsets

This is the memory map for the npc struct. This struct is not fully analysed. Any help is appreciated! Please note that the data may not be fully 100% accurate.

NPC Memory (0x158 bytes)
Name	Memory address	Memory type	Description
Attached layer name	NPC+0x00	VB6 String Pointer	The attached layer name. Can't be accessed via LunaScript. (Use either field attachedLayerObj or attachedLayerName)
Is in Quicksand?	NPC+0x04	FIELD_WORD	2 when the NPC is inside quicksand, 1 on the frame the NPC leaves quicksand
Unused Respawn delay	NPC+0x06	FIELD_WORD	Unused respawn delay. Supposed to be used by battle mode to determine when an npc should respawn but never read.
Bounce on floor flag	NPC+0x08	FIELD_BOOL	True if the NPC should bounce on the floor. Held/thrown by Toad/Peach or knocked forward by Link stab. Resets when touching the ground, but does not reset if Peach or Toad dropped the NPC without throwing it
Collides below	NPC+0x0A	FIELD_WORD	Set to 2 when touching a block below and briefly immediately after being thrown by the player (Use field collidesBlockBottom)
Collides left	NPC+0x0C	FIELD_WORD	Set to 2 when touching a block to the left (Use field collidesBlockLeft)
Collides above	NPC+0x0E	FIELD_WORD	Set to 2 when touching a block above (Use field collidesBlockUp)
Collides right	NPC+0x10	FIELD_WORD	Set to 2 when touching a block to the right (Use field collidesBlockRight)
Pushed vertically	NPC+0x12	FIELD_WORD	Set to 2 when pushed upwards by a layer or another NPC
Online Play held NPC timeout	NPC+0x14	FIELD_WORD	Unused Timeout for Held NPCs in Online Play.
Unknown	NPC+0x16	FIELD_WORD	Unknown
"Real" Speed X	NPC+0x18	FIELD_FLOAT	Speed X value without "speed" config modifier. Horizontal speed is copied into here before processing the speed config, and copied back after movement occurs.
Underwater Flag	NPC+0x1C	FIELD_WORD	Underwater state (2 is underwater, 0 is no). Any value greater than 0 makes it think its underwater.
Unused	NPC+0x1E	FIELD_WORD	Unused?
No Lava Splash	NPC+0x20	FIELD_BOOL	Whether or not an NPC won't have a splash in lava. True means no splash.
Index of Slope	NPC+0x22	FIELD_WORD	Block-array index of slope currently stood on.
Hit Counter (ie for hammers)	NPC+0x24	FIELD_WORD	Hit counter, for point calculation
Invincibility to Sword and Tail	NPC+0x26	FIELD_WORD	Invincibility frame countdown, for sword attacks and tail swipes (Use field invincibleToSword)
Draw only mask	NPC+0x28	FIELD_WORD	Draw only mask; Let this NPC go through solid blocks. (Use field drawOnlyMask)
Unknown	NPC+0x2A	FIELD_WORD	Unknown
Activate event layer name	NPC+0x2C	VB6 String Pointer	Activate event layer name. Can't be accessed via LunaScript. (Use field activateEventName)
Death event layer name	NPC+0x30	VB6 String Pointer	Death event layer name. Can't be accessed via LunaScript. (Use field deathEventName)
Talk event name	NPC+0x34	VB6 String Pointer	Talk event name. Can't be accessed via LunaScript. (Use field talkEventName)
No More Objs event layer name	NPC+0x38	VB6 String Pointer	No More Objs event layer name. Can't be accessed via LunaScript. (Use field noMoreObjInLayer)
Layer name	NPC+0x3C	VB6 String Pointer	Layer name. Can't be accessed via LunaScript. (Use field layerName)
isHidden	NPC+0x40	FIELD_BOOL	If the NPC is hidden. (Use field isHidden)
Legacy Boss	NPC+0x42	FIELD_BOOL	If the NPC is flagged as a boss. (Use field legacyBoss)
Activated	NPC+0x44	FIELD_BOOL	Activated / interacted with player flag
Friendly	NPC+0x46	FIELD_BOOL	Friendly (Use field friendly)
Don't Move	NPC+0x48	FIELD_BOOL	Don't Move (Use field dontMove)
Don't Move (Default value)	NPC+0x4A	FIELD_BOOL	Whether or not the NPC was originally set to Don't Move.
NPC Message text	NPC+0x4C	VB6 String Pointer	NPC Message text. Can't be accessed via LunaScript. (Use field msg)
Push Force	NPC+0x50	FIELD_FLOAT	Force exerted on the NPC to push it out of a block
Unknown	NPC+0x54	FIELD_WORD	Unknown
Unknown	NPC+0x56	FIELD_WORD	Unknown
Unknown	NPC+0x58	FIELD_WORD	Unknown
Unknown	NPC+0x5A	FIELD_WORD	Unknown
X-Speed of touched Object	NPC+0x5C	FIELD_FLOAT	X-Speed of touched NPC or Layer
Clown Car Player	NPC+0x60	FIELD_WORD	Index of Player in the clown car touched by the NPC
Distance from Clown Car	NPC+0x62	FIELD_WORD	Y-Distance from touched clown car
Is a generator	NPC+0x64	FIELD_BOOL	Is a generator? (Use field isGenerator)
Unknown	NPC+0x66	FIELD_WORD	Unknown
Generator delay setting	NPC+0x68	FIELD_FLOAT	Generator delay setting * 10 (Use field generatorInterval)
Generator delay countdown	NPC+0x6C	FIELD_FLOAT	Generator delay countdown (Use field generatorTimer)
Direction to generate NPC	NPC+0x70	FIELD_WORD	Direction to generate NPC or direction in which the NPC was generated. 1,2,3,4 correspond to up,left,down,right respectively. (Use field generatorDirection)
Generator type	NPC+0x72	FIELD_WORD	The generator type (1 = Warp; 2 = Projectile) (Use field generatorType)
Generator invalidity flag	NPC+0x74	FIELD_BOOL	Whether or not the generator can fire. Does not account for objects blocking the generator's spawn position
Player Standing on NPC?	NPC+0x76	FIELD_BOOL	Something to do with players. (needs testing)
X position	NPC+0x78	FIELD_DFLOAT	X position (Use field x)
Y position	NPC+0x80	FIELD_DFLOAT	Y position (Use field y)
Width	NPC+0x88	FIELD_DFLOAT	Width (Use field width)
Height	NPC+0x90	FIELD_DFLOAT	Height (Use field height)
X Speed	NPC+0x98	FIELD_DFLOAT	X Speed (Use field speedX)
Y Speed	NPC+0xA0	FIELD_DFLOAT	Y Speed (Use field speedY)
Spawn X	NPC+0xA8	FIELD_DFLOAT	Spawn X (Use field spawnX)
Spawn Y	NPC+0xB0	FIELD_DFLOAT	Spawn Y (Use field spawnY)
Spawn Width	NPC+0xB8	FIELD_DFLOAT	Spawn Width (Use field spawnWidth)
Spawn Height	NPC+0xC0	FIELD_DFLOAT	Spawn Height (Use field spawnHeight)
Spawn X Speed	NPC+0xC8	FIELD_DFLOAT	Spawn X Speed (Use field spawnSpeedX)
Spawn Y Speed	NPC+0xD0	FIELD_DFLOAT	Spawn Y Speed (Use field spawnSpeedY)
Spawn Direction	NPC+0xD8	FIELD_FLOAT	Direction the NPC is spawned in (Use field spawnDirection)
Respawn Id	NPC+0xDC	FIELD_WORD	Respawn Identity. 0 means doesn't respawn, otherwise same as 0xE2 (Use field spawnId)
Initial ai1 value	NPC+0xDE	FIELD_WORD	ai1 value on respawn. Contains ID of the "contained NPC" for container NPCs (Use field spawnAI1)
Initial ai2 value	NPC+0xE0	FIELD_WORD	ai2 value on respawn. Other ai values are always reset to 0 (Use field spawnAI2)
Id	NPC+0xE2	FIELD_WORD	Which type of NPC it is (Use field id)
Animation frame	NPC+0xE4	FIELD_WORD	Animation frame (Use field animationFrame)
NPC Array Index	NPC+0xE6	FIELD_WORD	Index of this NPC in the NPC Array (Use field idx)
Animation timer	NPC+0xE8	FIELD_FLOAT	Animation timer (Use field animationTimer)
Direction faced	NPC+0xEC	FIELD_FLOAT	Direction faced (Unknown difference from 0x118) (Use field direction)
NPC AI 1	NPC+0xF0	FIELD_DFLOAT	Multipurpose NPC AI state/timer 1 (Use field ai1)
NPC AI 2	NPC+0xF8	FIELD_DFLOAT	Multipurpose NPC AI state/timer 2 (Use field ai2)
NPC AI 3	NPC+0x100	FIELD_DFLOAT	Multipurpose NPC AI state/timer 3 (Use field ai3)
NPC AI 4	NPC+0x108	FIELD_DFLOAT	Multipurpose NPC AI state/timer 4 (Use field ai4)
NPC AI 5	NPC+0x110	FIELD_DFLOAT	Multipurpose NPC AI state/timer 5 (Use field ai5)
NPC AI 6	NPC+0x118	FIELD_FLOAT	Multipurpose NPC AI state/timer 6, rarely used (Use field ai6)
Player Input Y-Speed	NPC+0x11C	FIELD_FLOAT	Y-Speed influence through player input (used by glitchy airship piece)
Bounce off block	NPC+0x120	FIELD_BOOL	Bounced off a block to change direction this frame?
Kill flag	NPC+0x122	FIELD_WORD	Whether or not kill effects should apply. Uses harm types; see constants for the different harm types. Note: Harm types with "EXT" in the name only work NPC:harm(). (Use field killFlag)
On-screen Flag	NPC+0x124	FIELD_BOOL	This is set to false when an NPC resets its respawn position, but will not spawn itself fully because it's still visible by the player. Note 1: Must be set to true when spawning a new NPC. Note 2: This will be the behavior for TheXTech, only run the code when set to true.
On-screen Flag for Player 1 Camera	NPC+0x126	FIELD_BOOL	Is this NPC on-screen in the 1st player camera?
On-screen Flag for Player 2 Camera	NPC+0x128	FIELD_BOOL	Is this NPC on-screen in the 2nd player camera?
Despawn timer	NPC+0x12A	FIELD_WORD	Offscreen countdown timer. 180 is onscreen. Set to 0 to force despawn. This is set to -1 when an NPC is ready to respawn (but may not be able to if the player is close by) (Use field despawnTimer)
Player carrying index	NPC+0x12C	FIELD_WORD	The index of the player grabbing the NPC. Defaults to 0 when not grabbed, setting to 1 or higher deactivates block collision when grabbed but causes the respective player to drop other objects (Use field heldIndex)
Grab Timer	NPC+0x12E	FIELD_WORD	Related to grabbing npcs. Starts at 30 then quickly returns to 0 when released.
Grabbing Player	NPC+0x130	FIELD_WORD	Index of Player grabbing the NPC, resets at the top of the release arc
Thrown by Player	NPC+0x132	FIELD_WORD	Which Player threw the NPC. Resets when NPC resumes normal behaviour.
Wall Death Timer	NPC+0x134	FIELD_WORD	Used for NPC's being crushed. If inside a block while this is greater than or equal to 5, most NPC's will die (with exceptions, such as springs). Forcing to 0 can prevent the NPC from dying when thrown into a wall.
Projectile Flag	NPC+0x136	FIELD_BOOL	If true, the NPC can harm other NPC's. Usually true for NPC's like fireballs and being thrown by a player. (Use field isProjectile)
Forced State	NPC+0x138	FIELD_WORD	The NPC's forced state/effect/contained within value. The following values that it can have are: 0: Normal behaviour 1: Coming out of the top of a block (0x13C is how far it has come out) 2: Falling down from the player's item box (0x13C is a blinking timer, invisible if it is an interval of 3) 3: Coming out of the bottom of a block (0x13C is how far it has come out) 4: Coming out of a warp generator (0x13C is where it is being spawned from, 0x144 is the direction it's coming from (1,2,3,4 corresponds to up,left,down and right respectively)) 5: On Yoshi's tongue (0x13C is the player it belongs to, 0x144 is a countdown timer that returns it to state 0 if it reaches 0) 6: In Yoshi's mouth (0x13C is the player it belongs to) 8: Makes the NPC invisible (0x13C is a countdown timer that returns it to state 0 if it reaches 0) (used for subcon potion's "poof" effect) 208: In a mother brain jar, if not touching a jar it'll return to 0 (may only work fully properly for mother brain!) (Use field forcedState)
Forced State Timer 1	NPC+0x13C	FIELD_DFLOAT	General purpose "timer" for forced states. See 0x138 for how each state uses it. (Use field forcedCounter1)
Forced State Timer 2	NPC+0x144	FIELD_WORD	General purpose "timer" for forced states. See 0x138 for how each state uses it. (Use field forcedCounter2)
Current Section	NPC+0x146	FIELD_WORD	Current section this NPC is on (Use field section)
Hit Count	NPC+0x148	FIELD_FLOAT	Boss Hit count
Spawned by Camera	NPC+0x14C	FIELD_WORD	Index of the Camera which spawned the NPC in this frame
P-Switch Block ID	NPC+0x14E	FIELD_WORD	ID of the block they were created from due to p-switch
Block Array Index	NPC+0x150	FIELD_WORD	Index of NPC in an array involving blocks. Appears to only count for NPCs affected by the npcblocktop flag
NPC Collision	NPC+0x152	FIELD_BOOL	Seems to be set to true for a bullet when it destroys another NPC. May apply to all 0x136-related collisions but untested.
"No Turn Back" Flag	NPC+0x154	FIELD_WORD	Spawned NPC flag for "No Turn Back" section
Invincibility frames	NPC+0x156	FIELD_WORD	Invincibility frame countdown for all sources of harm