NPC (class)

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 using NPC.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	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.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. (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. (Use 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
Collides above	NPC+0x0E	FIELD_WORD	Set to 2 when touching a block above
Collides right	NPC+0x10	FIELD_WORD	Set to 2 when touching a block to the right
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. (needs testing)
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
Unknown	NPC+0x28	FIELD_WORD	Unknown
Unknown	NPC+0x2A	FIELD_WORD	Unknown
Activate event layer name	NPC+0x2C	VB6 String Pointer	Activate event layer name
Death event layer name	NPC+0x30	VB6 String Pointer	Death event layer name
Talk event name?	NPC+0x34	VB6 String Pointer	Talk event name?
No More Objs event layer name	NPC+0x38	VB6 String Pointer	No More Objs event layer name
Layer name	NPC+0x3C	VB6 String Pointer	Layer name
isHidden	NPC+0x40	FIELD_BOOL	If the NPC is hidden.
Legacy Boss	NPC+0x42	FIELD_BOOL	If the NPC is flagged as a boss.
Activated	NPC+0x44	FIELD_BOOL	Activated / interacted with player flag
Friendly	NPC+0x46	FIELD_BOOL	Friendly
Don't Move	NPC+0x48	FIELD_BOOL	Don't Move
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
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?
Unknown	NPC+0x66	FIELD_WORD	Unknown
Generator delay setting	NPC+0x68	FIELD_FLOAT	Generator delay setting * 10
Generator delay countdown	NPC+0x6C	FIELD_FLOAT	Generator delay countdown
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.
Generator type	NPC+0x72	FIELD_WORD	The generator type (1 = Warp; 2 = Projectile)
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
Y position	NPC+0x80	FIELD_DFLOAT	Y position
Height	NPC+0x88	FIELD_DFLOAT	Height
Width	NPC+0x90	FIELD_DFLOAT	Width
X Speed	NPC+0x98	FIELD_DFLOAT	X Speed
Y Speed	NPC+0xA0	FIELD_DFLOAT	Y Speed
Spawn X	NPC+0xA8	FIELD_DFLOAT	Spawn X
Spawn Y	NPC+0xB0	FIELD_DFLOAT	Spawn Y
Spawn Height	NPC+0xB8	FIELD_DFLOAT	Spawn Height
Spawn Width	NPC+0xC0	FIELD_DFLOAT	Spawn Width
Unused	NPC+0xC8	FIELD_DFLOAT	Unused
Unused	NPC+0xD0	FIELD_DFLOAT	Unused
Spawn Direction	NPC+0xD8	FIELD_FLOAT	Direction the NPC is spawned in
Respawn Id	NPC+0xDC	FIELD_WORD	Respawn Identity. 0 means doesn't respawn, otherwise same as 0xE2
Initial ai1 value	NPC+0xDE	FIELD_WORD	ai1 value on respawn. Contains ID of the "contained NPC" for container NPCs
Initial ai2 value	NPC+0xE0	FIELD_WORD	ai2 value on respawn. Other ai values are always reset to 0
Id	NPC+0xE2	FIELD_WORD	Which type of NPC it is
Animation frame	NPC+0xE4	FIELD_WORD	Animation frame
NPC Array Index	NPC+0xE6	FIELD_WORD	Index of this NPC in the NPC Array
Animation timer	NPC+0xE8	FIELD_FLOAT	Animation timer
Direction faced	NPC+0xEC	FIELD_FLOAT	Direction faced (Unknown difference from 0x118)
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)
Direction faced	NPC+0x118	FIELD_FLOAT	Direction faced
Player Input Y-Speed	NPC+0x11C	FIELD_FLOAT	Y-Speed influence through player input (used by 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().
Respawned, but onscreen	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: Must be set to true when spawning a new NPC
Offscreen flag	NPC+0x126	FIELD_BOOL	Same as 0x128?
Offscreen flag	NPC+0x128	FIELD_BOOL	Offscreen flag
Offscreen countdown 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)
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
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.
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!)
Forced State Timer 1	NPC+0x13C	FIELD_DFLOAT	General purpose "timer" for forced states. See 0x138 for how each state uses it.
Forced State Timer 2	NPC+0x144	FIELD_WORD	General purpose "timer" for forced states. See 0x138 for how each state uses it.
Current Section	NPC+0x146	FIELD_WORD	Current section this NPC is on
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.
Unknown	NPC+0x154	FIELD_WORD	Unknown
Invincibility frames	NPC+0x156	FIELD_WORD	Invincibility frame countdown for all sources of harm