ANP: How it's Done

The ANP command is a cryptic and confusing one, yet very powerful if used correctly. It is what allows you to orchestrate cutscenes, activate objects, and do other interactions with the entities on your map. This tutorial aims to help you understand the proper use of the ANP command, what each of its parameters means, and what can and cannot be done with the command.

So what's ANP mean?

ANP stands for Animate NPc. However, this description of the term is a little misleading; there are no such thing as "generalized animations" in cave story. Every single NPC is essentially a finite state machine.

Some entities, like the critter, are entirely autonomous; all their states can be reached through the normal behaviour of the entity. Others, typically character NPCs, have a number of action paths they can take that don't always link together.
The number in each bubble on the diagram is what I'll refer to as the entity's scriptstate. When an entity is created for the first time, it always has a scriptstate of zero, which is typically used to try and "reset" the entity. I would like to repeat that none of the animations are general. Every entity has its own set of states, and while there may be some patterns in the way Pixel designs them, there is no rule that says any one has to be like another.

Well, what does ANP do?

The primary function of ANP is to override the scriptstate and direction of a particular NPC (or group of NPCs), forcing it to suddenly behave in a different way. The ANP command will not change any other variables of the entity, so if the code was expecting a natural transition to the new state forcing it may have unexpected results. Most entities that are meant for use with the <ANP command have special measures to make sure that previous states won't impact a new animated state.

The Parameters

The ANP command has the format <ANPXXXX:YYYY:ZZZZ

• X: NPC
  The NPC parameter is how the game decides which entities to apply the new scriptstate to. Like most commands on entities, this searches by the Event Number of the entity. If more than one entity on the map has the same event number, the animation is applied to all of them. Entities spawned during play by other entities or commands like <SNP all have an event number of zero.
• Y: Animation
  The animation parameter is the new scriptstate that will be applied to the affected entities. Applying an unsupported scriptstate to an entity may either do nothing, make it behave strangely, or cause a crash, depending on the entity.
• Z: Direction
  The direction parameter is not always used, and its meaning is different between all the different entities that *do* use it. Generally speaking, use 0000 to represent right and 0001 to represent left. Sometimes the direction can be the direction the sprite moves, or sometimes it can signify a different sprite as in the case of door entities. If you are unsure, use 0000.

Don't forget that TSC parameters always need to be 4 characters long or you will die

Example

This example code assumes that we have an entity of type 150 (Quote) on the map with an event number 123.

#0100
<ANP0123:0050:0001<WAI0050<ANP0123:0002:0000
<WAI0025<CNP0123:0018:0000<END

This example would make Quote walk left for 50 frames, stop, look up, then turn into a door when event #0100 is run.

Final considerations:

For a sort-of complete list of available character animations, check anp.txt. All the values in this listing were determined empirically, so some states (such as 11 for quote) aren't necessarily "meant" to be animated to, but the result is still described.
If you use assembly to write your own NPCs, the scriptstate variable is [+0x74] and the direction variable is [+0x4C]. Design with this in mind if you want to be able to use ANP with your own entities.

Author: Noxid