NPC Entry INI config (Config pack)

npc-*.ini - the settings file which declares single entry of NPC types. When this file is a part of config pack, almost all parameters are required. The default location of theese files is specifying in the main lvl_npc.ini file by "config-dir" field of "[npc-main]" section.

When this file is created inside level or episode, all parameters are optional: the role of episode/level side configuration is overriding of default properties are declared on a side of config pack.

[ npc ]
Parameter	Allowed values	Example value	Description
Common values
name	string	name = "Furba"	Name of NPC
group	string	group = "Talkhaus сommon"	Group where NPC is member
category	string	category = "Enemy"	Category of this NPC
description	string	description = "Small, but danger creature!"	A short description about this element.
extra-settings	string	extra-settings = "mylayout.json"	Filename of GUI layout for extra settings if they are needed for this element. See Extra Settings JSON Layout for detailed specification of this config.
is-meta-object	boolean	is-meta-object = false	Make this element be meta-object: It will be hidden on exported images/screeshots in dependence from a choice.
hide-on-exported-images	boolean	hide-on-exported-images = false	Alias to "is-meta-object".
image	string	image = "npc-1.png"	Name of image file which a sprite for this NPC. Same image filename will be used as custom sprite in level/episode folders.
editor-image	string	editor-image = "npc-1e.png"	An alternative sprite image file name for the Editor. Leave it blank to keep the default sprite.
algorithm	string	algorithm = "furba.lua"	Filename of default algorithm script for this NPC
default-effect	>=1	default-effect = 2	Default effect which will be played when NPC was stomped
shell-effect	>=1	shell-effect = 4	Default effect which will be played when NPC killed by item
block-spawn-type	0, 1	block-spawn-type = 1	Block spawn effect: 0 - smooth warping, 1 - bumped
block-spawn-speed	>=0.0	block-spawn-speed = 3.2	Bump speed (Bumped type only)
block-spawn-sound	0, 1	block-spawn-sound = 1	Play sound on NPC spawn from a block
is-star	[0,1]	is-star = 1	Special marker which will mark this NPC as star - a special items which requiring to collecting which uses in some games and episodes.
Physics and mechanics
physical-width	>=1	physical-width = 32	Width of NPC's hitbox
physical-height	>=1	physical-height = 32	Height of NPC's hitbox
block-npc	[0,1]	block-npc = 1	NPC is a solid object for other NPCs from side
block-npc-top	[0,1]	block-npc-top = 1	Other NPC's can stand on top of this NPC
block-player	[0,1]	block-player = 0	NPC is a solid object for player. NPC will can push player.
block-player-top	[0,1]	block-player-top = 0	Player can stand on top of this NPC
collision-blocks	[0,1]	collision-blocks = 1	Enable collision with a blocks. You can disable collision if you want to create, for example, a ghost.
gravity	[0,1]	gravity = 1	Enable gravity for this NPC. If you will disable it, NPC will fly in the air.
adhesion	[0,1]	adhesion = 1	Allows NPC to walk on walls and on ceilings like insects
container	[0,1]	container = 0	NPC can hold inside another NPC (special option type 2 is required)
container-elastic	[0,1]	container-elastic = 0	Elastic sprite of container (like sizable block)
container-elastic-border-w	>=1	container-elastic-border-w = 0	Width of border to draw elastic container
container-show-contents	[0,1]	container-show-contents = 0	Show contents of container in the game process
container-content-z-offset	floating point number	container-content-z-offset = 0	Draw contents over or under main sprite of the NPC
container-crop-contents	[0,1]	container-crop-contents = 0	Drawn sprite of contents will cropped with physical size box of the container
container-align-contents	[0,1,2]	container-align-contents = 0	Y-align of contents sprite. 0 - align at center, 1 - align top-to-top, 2 - align top-to-bottom.
contact-padding	double	contact-padding = -1.0	Padding of contact detection zone (working only when NPC itself has no blocking sides)
no-npc-collisions	[0,1]	no-npc-collisions = 0	Editor specific flag: NPC can be placed over other NPC's without blocking but with anti-flood protection which preventing placement of NPC over another same NPC
Graphics
gfx-offset-x	integer	gfx-offset-x = 0	Horizontal offset of GFX image relative to center.
gfx-offset-y	integer	gfx-offset-y = 0	Vertical offset of GFX image relative to bottom.
gfx-height	>=1	gfx-height = 32	Height of visible GFX frame. By default calculating automatically from number of frames and framestyle values. Use it only if you getting incorrect GFX size.
gfx-width	>=1	gfx-width = 32	Width of visible GFX frame. By default calculating automatically from number of frames and framestyle values. Use it only if you getting incorrect GFX size.
editor-gfx-offset-x	integer	editor-gfx-offset-x = 0	Editor alternative horizontal offset of GFX image relative to center. Leave undefined to the generic value.
editor-gfx-offset-y	integer	editor-gfx-offset-y = 0	Editor alternative vertical offset of GFX image relative to bottom. Leave undefined to the generic value.
editor-gfx-height	>=1	editor-gfx-height = 32	Editor alternative height of visible GFX frame. By default calculating automatically from number of frames and framestyle values. Use it only if you getting incorrect GFX size. Leave undefined to the generic value.
editor-gfx-width	>=1	editor-gfx-width = 32	Editor alternative width of visible GFX frame. By default calculating automatically from number of frames and framestyle values. Use it only if you getting incorrect GFX size. Leave undefined to the generic value.
physics-to-gfx	[1,0]	physics-to-gfx = 1	Allows users to map Physical size to GFX size setup in their custom npc.txt config files. Default 1
frame-style	0..2	frame-style = 0	Declares how many framesets sprite sheet has: 0 - Symmetric item with full frameset. Frames count equal to count of actual frames count on sprite sheet 1 - Asymmetric item with left and right direction frames. Sprite dividing to 2 framesets for left and right directions. 2 - Asymmetric item with left, right and turned upper frame sets. Sprite has a 4 framesets for left-right direction states and turn upper left-right states Note: This option may be ignored in some algorithms
frames	>=1	frames = 2	Number of physical frames on the sprite sheet per frameset (use frame-style value to set a count of framesets) Note: Don't forget about frame styles: framestyle 0 uses whole frameset of sprite, so you can count all frames on sprite and set up. 1 has a two framesets for left and rigth directions where you should count a half of whole frameset on sprite. 2 users four framesets on sprite, so you need to count quoter of presented frames on your sprite. Some algorithmic NPC's can have custom framestyles which aren't compatible with current stuff Note: If you want to use only one or some of frames in a range, don't use frames=1 as this will say that entire sprite contains only one frame! Instead, declare the custom frame sequence over the physical count of frames by using editor-animation-sequence related fields
editor-frames	>=1	editor-frames = 128	Editor alternative frames count. Leave undefined to use a generic value.
frame-delay	>=1	frame-delay = 128	Delay between animation frames in milliseconds.
frame-speed	>=1	frame-speed = 128	Alias to frame-delay
framespeed	>=1	framespeed = 8	Delay between animation frames in 1/65 seconds units (for the compatibility to the SMBX Engine)
display-frame	>=1	display-frame = 128	Default static frame in the editor with a disabled animation.
foreground	[1,0]	foreground = 0	Set the npc foregroung Z-Layer. Sprite will be drawn over others but under foreground-2 BGO's
background	[1,0]	background = 0	Set the npc background Z-Layer. Sprite will be drawn over sizalbe blocks but under background BGO's
z-offset	+/- floating point number	z-offset = 0	Z-order offset modifies render priority
animation-directed-direction	[1,0]	animation-directed-direction = 1	Inverse order of animation frames dependent to direction of NPC
animation-direction	[0,1]	animation-direction = 0	Direction of animation order: 0 - direct sequence, 1 - reverse frame sequence
animation-bidirectional	[0,1]	animation-bidirectional = 0	Bidirectional animation: order of frames sequence will be turned back on edge frame
Alignment
grid	>=1	grid = 32	Sets the align grid size
grid-offset-x	integer	grid-offset-x = 0	Horizontal align offset relative to grid point. Note: Value must be less than half of grid size to keep aligning correct
grid-offset-y	integer	grid-offset-y = 0	Vertical align offset relative to grid point Note: Value must be less than half of grid size to keep aligning correct
grid-attachment-style	[1,0]	grid-attachment-style = 1	0 - Align NPC Item's center to horizontal center of grid cell (default) 1 - Align NPC Item's center to edge of cells. Preview (left is "1", right is "0")
Editor specific animation
editor-animation-sequence	Array of unsigned integers	editor-animation-sequence = "0,2,0,1"	Common animation frames sequence (for both directions). If not set, default animation will play. Tip: Frame indices are relative to the direction of the NPC, dependent on frame style. For example, with frame style 1, frame 0 of the animation for the right direction will start in the middle of the NPC sprite sheet.
editor-animation-sequence-left	Array of unsigned integers	editor-animation-sequence-left = "0,2,0,1"	Common animation frames sequence (for left direction, common will be overwritten).
editor-animation-sequence-right	Array of unsigned integers	editor-animation-sequence-right = "0,2,0,1"	Common animation frames sequence (for right direction, common will be overwritten)
Custom values settings
custom-value-enabled	[0,1]	custom-value-enabled = 0	Use the special NPC's option which can used to make NPC Algorithm more flexible and configurable
custom-value-name	string	custom-value-name = "Mood level"	Title for the special value
custom-value-type	[0,1,2]	custom-value-type = 0	Defines type of control element which will be used to setup special value: 0 - combobox 1 - spin box 2 - npc-id dialog button
custom-value-combobox-size	>=1	custom-value-combobox-size = 3	Number of combo box items
custom-value-option-*	string	custom-value-option-* = "I'm happy!"	Define of each combo box item (where '*' should be an index of each combo box item, begins from 0 and ends with 'number of items'-1 )
custom-value-spin-min	integer	custom-value-spin-min = 0	Minimal value of spin box
custom-value-spin-max	integer	custom-value-spin-max = 25	Maximal value of spin box
custom-value-spin-value-offset	integer	custom-value-spin-value-offset = 1	Offset value which will be apply into visible in the editor value. For example, if offset is +1, in the editor will be shown 25 but in the configuration will be sated the 24 value.
Gameplay settings
score	[0....13]	score = 2	Scores which player will get when take or kill this NPC 0, 10, 100, 200, 400, 800, 1000, 2000, 4000, 8000, 1up, 2up, 5up, 3up
speed	>=0	speed = 64	Default movement speed in px/s
moving	[0,1]	moving = 1	Enable built-in simple movement right/left algorithm
static-body	[0,1]	static-body = 0	Makes NPC as static body which can't be moved from side (like blocks)
keep-position	[0,1]	keep-position = 0	NPC will not be returned to initial position on despawn
shared-animation	[0,1]	shared-animation = 1	If value 0, NPC will use global shared animator and all NPC's of this type will are have same animation sequence
activity	[0,1]	activity = 1	NPC will have onLoop() event and will do AI. If flag is 0, NPC will keep new state while level will not be finished or replayed. Set 0 value, for example, to coins and 1 value for living enemies or grabbable items.
immortal	[0,1]	immortal = 0	NPC Can't be killed or destroyed
can-be-eaten	[0,1]	can-be-eaten = 0	NPC Can be eaten with using of animal transports (Catnip, Yoshi)
takable	[0,1]	takable = 0	Make NPC Destroyable on contact with player
grab-side	[0,1]	grab-side = 0	NPC Can be grabbed from side
grab-top	[0,1]	grab-top = 0	NPC can be grabbed from top
grab-any	[0,1]	grab-any = 0	NPC can be grabbed from any contact points
default-health	>=1	default-health = 1	NPC Health value. By default NPC can be killed from one hit.
hurtplayer	[0,1]	hurtplayer = 1	NPC will hurt player on contact
hurtplayer-on-stomp	[0,1]	hurtplayer-on-stomp = 1	NPC will hurt player on attempt to stomp it
hurtplayer-on-spinstomp	[0,1]	hurtplayer-on-spinstomp = 1	NPC will hurt player on attempt to stomp it in a spinning state
hurtnpc	[0,1]	hurtnpc = 0	Hit another npc on contact with them
damage-sensitive-stomp	integer	damage-sensitive-stomp = 1	Damage points from a stomp attack of player
damage-sensitive-spinstomp	integer	damage-sensitive-spinstomp = 1	Damage points from a stomp attack of player in a spinning state
damage-sensitive-itemkick	integer	damage-sensitive-itemkick = 1	Damage points from any objects thrown by player
Sound effects
takable-sound-id	>=0	takable-sound-id = 42	Play the sound by ID when NPC got takenas a coin or a bonus
hit-sound-id	>=0	hit-sound-id = 42	Play the sound by ID when NPC got a non-lethal hit
death-sound-id	>=0	death-sound-id = 42	Play the sound by ID when NPC dies
NPC Direction value features
direction-alt-title	string	direction-alt-title = "Activity"	Alternate title of "direction" option
direction-alt-left-field	string	direction-alt-left-field = "On"	Alternate title of "left direction" option
direction-alt-right-field	string	direction-alt-right-field = "Off"	Alternate title of "right direction" option
direction-no-rand-field	[0,1]	direction-no-rand-field = 1	Disallow usage of random direction value
direction-default-value	[-1,0,1]	direction-default-value = -1	Declares a default direction value for this NPC: -1 - left, 0 - random, +1 - right. Field is supported since August 5, 2019.
Default values of flags in the editor
default-friendly	[0,1,-1]	default-friendly = 0	Friendly flag. When value is set to -1, the last state of a friendly flag should be re-used.
default-no-movable	[0,1,-1]	default-no-movable = 0	"Doesn't move" (No movement) flag. When value is set to -1, the last state of a no-movable flag should be re-used.
default-is-boss	[0,1,-1]	default-is-boss = 0	"Set as boss" (SMBX Legacy Boss) flag. When value is set to -1, the last state of the "is-boss" flag should be re-used.
default-special-value	integer >=0 or -1	default-special-value = 0	Default value of special parameter. When value is set to -1, the last state of a special value should be re-used.
Events
deactivate	[0,1]	deactivate = 1	Deactivate NPC after 4 sec offscreen. Deactivation will return NPC into initial state and NPC will be activated again if it will appear on screen after deactivation
deactivate-delay	>=0	deactivate-delay = 4000	Deactivation timeout
deactivate-off-room	[0,1]	deactivate-off-room = 0	Deactivate NPC outed off section
bump-on-stomp	[0,1]	bump-on-stomp = 1	Playable character will be bumped on stomp
kill-slside	[0,1]	kill-slside = 1	NPC can be killed while player sliding on slope
kill-onjump	[0,1]	kill-onjump = 1	NPC can be killed by stomp on head
kill-bynpc	[0,1]	kill-bynpc = 1	NPC can be killed by NPC which thrown by player or kill by contact with npc-hurtful NPC's. for example: moving SHELLs have "HURT_NPC", and shell kills ALL NPCs on contact.
kill-on-pit-fall	[0,1]	kill-on-pit-fall = 0	NPC will die on falling down out of section (falling into the pit)
kill-fireball	[0,1]	kill-fireball = 1	NPC can be killed by fire ball shooting
kill-iceball	[0,1]	kill-iceball = 1	NPC can be frozen by ice ball shooting
kill-hammer	[0,1]	kill-hammer = 1	NPC can be killed by hammer shooting
kill-tail	[0,1]	kill-tail = 1	NPC can be killed by tail punch
kill-spin	[0,1]	kill-spin = 1	NPC can be killed by stomp with spin
kill-statue	[0,1]	kill-statue = 1	NPC can be stomped by statue fall
kill-with-mounted	[0,1]	kill-with-mounted = 1	NPC can be killed with mounted transports (like big shoes, magic sacks, helicopters )
kill-on-eat	[0,1]	kill-on-eat = 1	NPC will die when will be eaten
cliffturn	[0,1]	cliffturn = 1	NPC will turn on a cliff edge
lava-protection	[0,1]	lava-protection = 1	NPC will not be burned in lava
Level exit
is-exit	[0,1]	is-exit = 1	Killing/taking of this NPC will trigger exiting of the level.
exit-direction	[-1,0,1]	exit-direction = 1	Direction where player will walk when exit was trigger
exit-code	[>=1]	exit-code = 1	Return level exit code to world map.
exit-delay	[>=0]	exit-delay = 4500	Delay in milliseconds before level will be exited.
exit-sound-id	[>=0]	exit-sound-id = 19	Play sound by ID when NPC has been killed/taken and when exit has been triggered.
is-climbable	[0,1]	is-climbable = 1	Turn NPC into the climbable fence/vine/treetrunk/ladder/etc.
Deprecated values.
scenery	[0,1]	scenery = 0	Alias to "static-body".
framecount	>=1	framecount = 128	Alias to frames
frame-count	>=1	frame-count = 128	Alias to frames
have-special	[0,1]	have-special = 0	Alias to "custom-value-enabled", Deprecated.
special-name	string	special-name = "Mood level"	Alias to "custom-value-name", Deprecated.
special-type	[0,1,2]	special-type = 0	Alias to "custom-value-type", Deprecated.
special-combobox-size	>=1	special-combobox-size = 3	Alias to "custom-value-combobox-size", Deprecated.
special-option-*	string	special-option-* = "I'm happy!"	Alias to "custom-value-option Deprecated.
special-spin-min	integer	special-spin-min = 0	Alias to "custom-value-spin-min" Deprecated.
special-spin-max	integer	special-spin-max = 25	Alias to "custom-value-spin-max", Deprecated.
special-spin-value-offset	integer	special-spin-value-offset = 1	Alias to "custom-value-spin-value-offset", Deprecated.
yoshicaneat	[0,1]	yoshicaneat = 0	Alias to "can-be-eaten".