Jazz Jackrabbit 2 Online

NPC Bunnies / NPC Designer

This script adds non-player characters (NPCs) to Jazz Jackrabbit 2 levels, with the goal of giving level creators another way to bring their maps and stories to life.

NPCs can do considerably more than simply stand in one place and display a line of text. They can talk to players, participate in conversations with other NPCs, ask questions, offer choices, give quests and rewards, run shops, follow players, guide them through the level and even fight monsters alongside them. Multiple NPCs can follow the same player at once.

The system includes an in-game NPC Designer/Editor, allowing most of this to be created and edited without manually writing the NPC data file.

The Designer itself also contains a Help menu, and !npcHelp can be used to open the instructions separately. Several of the more specialized editor screens, such as guide-path editing, also display their own instructions directly in-game. Therefore, this description is intended to explain what the script can do and give an overview of its systems; you do not need to memorize everything here before using the editor.

The download contains two folders. Which one should you use?

Release contains the version intended for normal use. The NPC systems, Designer, dialogue/quest/shop code, help menus and other AngelScript modules have been joined into a single npcBunnies_Release.asc file. This is the version I recommend using in finished levels.

Build contains the modular source code that I actually use while developing NPC Bunnies. I keep the different systems in separate .asc files because maintaining a project of this size as one enormous source file would be considerably more difficult.

I also use my own offline build script, included in the Build folder as npcBuildScript.bat and npcBuildScript.ps1. Running it combines the modular source files in the correct order and generates a new npcBunnies_Release.asc.

Therefore, if you simply want to use NPC Bunnies, use the files in Release. The Build folder is mainly provided for people who want to examine, modify or build the source themselves.

Adding NPC Bunnies to a level

NPC Bunnies comes with both a script and a mutator version.

For a level that is intended to use NPCs permanently, I recommend including the script directly from the level’s .j2as file:

#pragma require “npcBunnies.asc”
#include “npcBunnies.asc”

If the .j2as file does not already exist, create a text file with the same filename as your level and change its extension to .j2as.

The .mut version can be useful while designing or testing levels, since it allows the NPC system to be loaded without first modifying the level script. For a finished level, however, I recommend the script version so that NPC Bunnies is loaded only by levels that actually use it.

NPC Designer

The NPC Designer can be opened with:

!npcEdit
!npcEditor
!npcDesigner

The server can use the Designer directly. Remote admins can also be given access through an NpcBunniesAdmin section in admin.ini. A sample configuration is included as npcAdminSample.ini.

Players who do not have editing permission can still use: !npcHelp to read the NPC help menu.

The Designer can be controlled with the mouse or keyboard. Many menus contain additional instructions directly inside the interface.

At the top of the Designer there is also an Enable player movement: ON/OFF option. This allows the editor to decide whether normal player movement should remain available while working inside the Designer.

NPC Designer – Main Menu
The main menu contains the following options, in this order:
- Create NPC – Creates a new NPC and lets you choose its initial character.
- Edit NPC – Opens a list of the NPCs currently in the level and allows one to be edited.
- Delete NPC – Removes an NPC from the level.
- Undo delete – Restores the most recently deleted NPC in case it was removed accidentally.
- Big dialogue animations: ON/OFF – Controls whether the larger character artwork is used during conversations. When this is disabled, smaller heads or standing-character animations are used instead.
- All monster/boss animations: ON/OFF – By default, NPC Bunnies avoids unnecessarily loading every monster and boss animation. When this option is OFF, the Designer primarily offers monsters and bosses whose animation sets are already available. Turning it ON makes the full configured monster/boss selection available; when switching it on, the complete effect applies after the level restarts.

Existing NPCs do not lose their saved monster or boss type merely because its animation is not currently loaded.
- Load additional monsters – When the previous option is OFF, this menu allows individual monster and boss animation sets to be loaded as needed instead of loading all of them.
- Help – Opens the in-game documentation.
- Exit – Closes the NPC Designer.

Creating and choosing NPC types
When creating a new NPC, the initial creation screen offers the character NPCs. After the NPC has been created, its type can be changed from the Edit NPC menu.

NPCs can currently belong to five broad categories:
- Characters – Jazz, Spaz, Lori, Frog, Bird, Devan, Mario, Sonic, Tails, JJ1, Yoshi and Eva are available.
- Monsters – A large selection of normal JJ2 enemies can be used as NPCs.
- Bosses – Boss characters can likewise be used as NPCs.
- Objects – Several shields, monitors and weapon powerups can be used as NPC appearances.
- Static – A special NPC type intended for characters or objects that exist only as artwork in the level’s tileset. Instead of drawing a normal character or monster animation, the NPC uses the tileset artwork at its position while still gaining features such as dialogue, quests and shops.

As the name suggests, Static NPCs cannot perform movement-related actions such as following or guiding the player.

Editing an NPC
The Edit NPC menu presents the NPC’s settings in roughly the same order in which they are most likely to be needed:
- Name – Sets the NPC’s displayed name.
- Character / Type – Changes both the NPC category and the specific character, monster, boss, object or static type.
- Fur – Sets the four fur-color values used by compatible character NPCs.
- Size – Tiny, Normal or Giant.
- Speed – Controls movement speed for NPCs that can move.
- Hat – Selects the NPC’s hat.
- Scarf – Selects the scarf or bowtie.
- Glasses – Selects the glasses.

NOTE: Hat positions have been adjusted for the NPC characters. Scarves and glasses are still experimental and have not yet received the same amount of manual coordinate adjustment, so they may not be positioned correctly on every NPC or animation.

- Edit position – Allows the NPC to be repositioned directly.
- X / Y – Allows the position to be entered numerically.
- Change direction – Selects the direction the NPC initially faces.
- Can follow: ON/OFF – Determines whether the NPC may follow players.
- PUSHABLE: ON/OFF – Determines whether players can physically push the NPC away from its position.
- Fighting: ON/OFF – Makes the NPC capable of fighting monsters and bosses.
- Fighting style: Simple/Complex – Determines how a fighting NPC behaves.
- Edit dialogue – Opens the dialogue, question, choice, quest and reward editor.
- Edit shop – Configures a shop for the NPC.
- Has guide: ON/OFF – Allows the NPC to guide players along predefined routes.
- Edit guide – Creates and edits those guide routes.
- Trace – Gives moving NPCs an optional movement-afterimage effect. Available modes are OFF, ON, INVERTED and CONST.
- Trace color – Selects the JJ2 palette index used by the NPC trace.

Interacting with NPCs
When a player approaches an NPC, a Y prompt appears. Pressing Y opens that NPC’s interaction menu.
Depending on the features enabled for that particular NPC, the menu can contain:

- Talk – Begin the NPC’s dialogue.
- Follow / Stop Following – Ask the NPC to follow the player, or dismiss an NPC that is already following them.

More than one NPC can follow the same player. They arrange themselves into a following order rather than all trying to occupy exactly the same position.
- Shop – Opens the NPC’s shop.
- Guide – Asks the NPC to guide the player through one of its available guide paths.
- Fighting: ON/OFF – Allows the player to enable or disable that NPC’s fighting behavior if fighting was made available by the level creator.
- Return – Sends the NPC back toward its original level position.
- Exit – Closes the interaction.
Static NPCs have a reduced interaction menu because they cannot follow, guide or otherwise move around the level.

If you are the server or an authorized NPC Bunnies admin, approaching an NPC also displays an E prompt. Pressing E opens the Designer directly for that particular NPC, avoiding the need to find it manually in the Edit NPC list.

Following players
An NPC with Can follow: ON can be asked to follow a player from its interaction menu.

Multiple NPCs can follow a single player simultaneously. They are given positions within a following chain so that they do not all attempt to stand in the same place.

The movement system records and simplifies movement paths and includes behavior for jumping, catching up and dealing with larger distances.

NPC movement is intentionally not an exact duplicate of normal JJ2 player movement. Pathfinding and NPC movement can become relatively expensive when many characters are active, so the system uses a more limited movement and waypoint system to reduce unnecessary processing.

Likewise, only the character animations required by the NPC system are included rather than loading every normal player animation for every NPC.

NPC fighting
NPCs can optionally fight alongside players.

There are two fighting styles:
- Simple – The NPC follows the player’s lead. When the player fires, the NPC can respond with its own delayed shot in the direction in which the player is fighting.
- Complex – The NPC searches for nearby monsters and bosses, checks whether it has a suitable line of sight and independently fires at targets it can attack.
Fighting can be made available by the level creator and then toggled ON or OFF by the player through the NPC interaction menu.

For testing fighting NPCs and monster/boss quests, an authorized admin can use:

!respawnMonsters

This respawns missing supported monster and boss objects used for NPC testing.

Dialogue

Dialogue is organized into dialogue sets, allowing conversations to branch from one set into another rather than requiring every NPC interaction to be a single linear conversation.

The current dialogue types are:
- Dialogue – A normal conversation.
- TextAnswer – The NPC asks for a typed answer.
- Choices – The player selects from multiple possible responses. Up to four choices can be configured from the Designer, with each choice able to lead to another dialogue set.
- Quest – The dialogue starts or checks a quest and can grant rewards once its requirements have been completed.
Dialogue sets also include several tools for building more involved conversations.

Speaker can be changed so that another NPC in the level speaks a particular part of the conversation. This allows several NPCs to participate in the same scene instead of every line necessarily coming from the NPC whom the player initially approached.

Go to set allows one dialogue set to lead into another.

Normal dialogue sets can also use Auto-Continue to move automatically into another set.

When big dialogue animations are enabled, compatible NPCs can use the larger dialogue artwork and the editor allows the appropriate dialogue frame to be selected.

Quests and rewards
NPCs can give players quests as part of their dialogue.

Quest requirements currently include:

- collecting coins;
- collecting gems of a selected color;
- defeating a selected monster type;
- defeating a selected boss type.

A quest can contain more than one requirement.

The reward system is considerably broader. Rewards can include coins, gems, ammunition, weapon powerups, FastFire, teleportation, changing an NPC’s moveable state, changing a trigger, and unlocking part of an NPC guide route.

Quest dialogue can separately define what the NPC says while the quest is still in progress and what is said once the quest has been completed.

Monster/boss quests can also be configured to respawn the required enemies where appropriate.

Active Quest window

Players can view their active quests through the built-in quest tracker.

The default key is Q, and the window can also be opened with:

!quests

The quest tracker shows active objectives and their progress. Its information view can provide additional quest details, and the hotkey can be changed directly from the quest window.

The tracker window is draggable and remembers its local window/key preferences.

NPC shops
An NPC can also operate a shop.

The Designer allows each shop item to specify the item itself, its amount, its coin price, gem price and stock.

Stock can be limited or unlimited. Once limited stock reaches zero, the item is shown as sold out.

Shop items use the same underlying reward system, allowing NPCs to sell things such as ammunition, weapon powerups, FastFire and other applicable reward actions.

If an NPC has no shop items configured, the player simply sees:

This NPC sells no items.

NPC guides
An NPC with Has guide: ON can lead players through predefined routes.

The Guide editor allows you to add normal paths as well as teleport steps.

Normal guide paths are recorded directly in the level. The editor displays its own controls and instructions while recording: arrow keys are used to build the path, and returning to an earlier square can remove an unwanted loop.

Teleport entries can likewise be positioned visually and can define the direction the NPC faces after teleporting.

Each guide segment can have dialogue associated with it, allowing the NPC to say something before continuing along the route.

There are also separate lines for what the NPC says after reaching the final destination and what it says if the player asks to be guided again after already arriving.

Guide paths can even be connected to the quest reward system. This makes it possible for a quest to unlock a new part of a guide route only after the player has earned access to it.

NPC traces
Moving NPCs can optionally leave a short afterimage trace.

The trace setting offers:
- OFF – No trace.
- ON – A normal graduated-color trace.
- INVERTED – Reverses the normal trace shading.
- CONST – Uses the same selected palette color for every afterimage.

A palette index can be entered through Trace color.

Traces are generated while NPCs are following or guiding players, rather than being constantly produced by stationary NPCs.

Multiplayer synchronization
NPC Bunnies includes multiplayer synchronization for NPC state and movement so that important NPC behavior can remain consistent between the server and clients.

Synchronization includes information such as following state, position/direction, fighting state and accessory state. Position information is sent periodically rather than transmitting every NPC position every frame.

The server can enable or disable NPC synchronization with:

!npcSync ON
!npcSync OFF

This is an admin command. The setting is saved in npcSyncSetting.asdat and takes effect after a level cycle.

With synchronization disabled, runtime NPC synchronization packets are not used and each machine simulates the NPCs locally instead.

For normal multiplayer use, synchronization is enabled by default.

Performance and animation usage
NPC Bunnies can potentially place many animated and independently behaving characters into a level, so several parts of the script are designed with JJ2’s animation limits and processing cost in mind. The optimization present in my charsNew.mut is also present here: all the frames for one character is loaded into a single animation, thus avoiding the 1500 animation limit.

The character NPCs use a deliberately reduced set of movement animations rather than loading an entire normal player animation set for every character.

Likewise, monster and boss animations are not all loaded automatically by default. A level creator can load only those actually needed, or deliberately enable All monster/boss animations when the larger selection is more important than minimizing loaded resources.

NPC following uses a limited and simplified waypoint/pathfinding system rather than trying to reproduce every detail of player movement.

The drawing code also contains optimizations for levels containing larger numbers of NPCs, while NPC state and position synchronization is sent periodically rather than on every frame.

The aim is to make fairly elaborate NPC-populated levels possible without every optional feature automatically consuming resources simply because the script is present.

Saving NPCs

The NPC Designer automatically saves the NPC definitions for each level in:
_npc.asdat

This file contains the NPC positions and properties together with their dialogue, quests, rewards, shops, guide paths and other NPC-specific settings.

This also means that NPC content is associated with the particular level rather than requiring every NPC to be hardcoded into the script.

An example_npc.asdat file is included as a reference for level creators who want to examine or manually edit the data format.

Other small .asdat files are used for local preferences and script-wide settings, such as the quest tracker position/key and NPC synchronization setting.

Useful commands
- !npcHelp – Opens the NPC Bunnies help menu. This can be read even by players who do not have permission to edit NPCs.
- !npcEdit / !npcEditor / !npcDesigner – Opens the NPC Designer for the server or an authorized NPC Bunnies admin.
- !quests – Opens the player’s Active Quests window.
- !respawnMonsters – Admin command used to respawn missing monster/boss objects, particularly useful while testing NPC fighting and defeat quests.
- !npcSync ON/OFF – Admin command that changes multiplayer NPC synchronization. The new setting takes effect after a level cycle.

There is also an advanced NPC accessory-coordinate editor available to authorized admins through !npcHatEdit / !npcHatEditor. This is primarily intended for adjusting how hats, scarves and glasses are positioned rather than for normal level gameplay.

Again, many functions of the Designer explain themselves directly inside their respective menus, so the in-game Help button and !npcHelp are worth using while building a level.

Sample level
Ultra hotel 3.j2l has been included as an example level.

Credits

I want to thank FawFul, SuperJazz, Clank[NC] and Zero[CDF] for their help with the characters used by the NPC system, as well as Violet and Seren for the occasional scripting ideas and suggestions along the way.

I also want to thank k10-287[HsC], Usagi[NC] and Helga[NC] for their bug reports, and the whole NC clan for their patience and for helping me test the script throughout its development.

A special thanks goes to Fabian[NC], whose ideas helped inspire this script in the first place.

The development of NPC Bunnies has stretched over a long period of time, with many periods of active work followed by returning to it months later. If I have forgotten to mention anyone who helped, tested, reported a problem, contributed an idea or otherwise supported its development, please forgive the omission and let me know.