NPC Entry INI config (Config pack)

From Moondust Wiki
Jump to navigation Jump to search

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

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

Notice 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)
Notice 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

Notice 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

grid >=1 grid = 32 Sets the align grid size
grid-offset-x integer grid-offset-x = 0 Horizontal align offset relative to grid point.
Notice 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
Notice 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.
Notice 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.

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".