Jazz Jackrabbit 2 Online

This mutator greatly expands the playable characters in Jazz Jackrabbit 2. It does so without replacing Jazz or Spaz with different sprites: custom characters are drawn separately by the mutator, allowing all of them to exist simultaneously.

In addition to full characters, there are also novelty “head” characters, based on the player life HUD sprites. The system goes even further by allowing players to morph into monsters, bosses and even certain game objects, including food and monitors.

Using this custom character implementation, Lori is also made available in JJ2 1.23.

The characters are not merely cosmetic. Where appropriate, the mutator gives them their own behavior and abilities rather than simply having every character play identically.
- Frog is made into a much more usable playable character: he can run, cycle through weapons and fire ammunition through his tongue animation. The mutator also contains a special “forced frog” renderer to work around a JJ2 bug that can occur on very large levels. In such cases, the game has actually morphed the player into a frog, but may continue displaying an incorrect rabbit frame. Forced Frog hides this broken native sprite and draws the correct frog animation through the mutator instead.
- Bird can use the normal weapon inventory while flying, including switching weapons and firing its own airborne shots.
- Devan has a much more extensive custom animation and gameplay system, including his own movement, firing and idle animations, as well as his Devil Devan transformation, flight and alternate attack behavior.
- Witch can fly and, when her special abilities are enabled, use polymorph attacks capable of turning other players into frogs. Her shooting and death animations are represented as well.
- Eva is fully playable and has her own movement and kiss animations. Her special kiss reproduces Eva’s familiar gameplay role by reverting the morph of a player standing in front of her.
- The head characters also have special movement and flying behavior where appropriate, which can be enabled or disabled independently.
- Other special moves I will leave for you to discover while playing the custom characters.

Morphing and the Morph Menu

Players can morph either through chat commands or through the in-game Morph Menu.

!morphMenu – Opens or closes the Morph Menu.
!morphSettings – Opens the Morph Menu directly on its settings page.
!listMorphs – Displays the available character morph commands.

For normal characters, the command is simply ! followed by the character name shown in the Morph Menu. For example:
!jazz, !spaz, !lori, !frog, !bird, !devan, !eva, etc.
Alternatively, simply click a character’s name in the Morph Menu to morph into it.

Morph Menu – Pages 1 and 2
The first two pages contain the characters themselves. Regular characters are kept together on the first page, while the head characters appear on the second page.

Each character has two administrator-controlled columns:
- ON / OFF – Determines whether players are allowed to morph into that character. This is useful for maps or game modes that depend on particular characters or abilities.
- SPE / NORM – Determines whether the character uses its custom special abilities or falls back to the corresponding normal JJ2 abilities. This allows a server to keep a character available without necessarily giving it an advantage that would be unsuitable for the current map.
For example, you might want to allow Devan while preventing the use of his Devil Devan transformation and flight. Setting his movement mode to NORM allows the character to remain playable while removing the custom special move. This can help if you want to allow custom characters in gamemodes such as CTF, without allowing one to have an unfair advantage.
These settings are automatically saved for future games.

Monster Morphs
Monster and boss morphs use a separate command:
!monster – Morphs into a JJ2 monster or boss.

Examples:
!monster xmasturtle
!monster hatter
!monster fencer
!monster robot

!monster off – Returns from a monster morph.

Object morphs
Certain JJ2 objects can also be used as playable appearances.
!object – Morphs into a supported object, such as food, pickups or monitors.

Examples:
!object apple
!object blasterpowerup
!object carrot

!object off – Returns from an object morph.

Character, monster and object morphs respect the player’s fur colors where their graphics make use of JJ2’s player palette.

Character size
The mutator also takes inspiration from giant.mut, integrating character resizing directly into the custom character system so it works correctly with the additional characters and morphs.

!tiny – Makes your character tiny.
!normal – Restores normal size.
!giant – Makes your character giant.

The equivalent commands !size tiny, !size normal, !size giant and !char tiny/normal/giant may also be used. Character size is synchronized to other players.

Morph Menu – Page 3: Settings

The third page contains the global administrator settings first, followed by settings that each player can control for themselves. It can be displayed by typing the !morphSettings command.

ADMIN OPTIONS

- Pregame only option
When enabled, players may only change their character during the pregame period.
This can be useful in game modes where changing character in the middle of play could provide an unwanted tactical advantage.

- Hang on ledges option
Enables the ledge-hanging system globally.
The feature allows Jazz and Spaz to catch suitable ledges while falling. It was inspired by the hangOnLedges mutator, but needed to be integrated directly into this character system so that ledge hanging does not activate for unsuitable custom characters or conflict with their custom animations.
Individual players may disable the feature for themselves separately.

- Hiding option
!charHide ON/OFF – Administrator command
Enables or disables character hiding globally.
When enabled, crouching while sufficiently covered by foreground scenery can hide the player’s character instead of leaving the custom sprite visibly poking through something that should conceal it.

- Monster morphs option
!monsterMorphs ON/OFF – Administrator command
Allows or completely disables monster and boss morphing on the server.
When disabled, players cannot use !monster to begin a new monster morph.

- Object morphs option
!objectMorphs ON/OFF – Administrator command
Allows or disables object morphing on the server.
When disabled, players cannot use !object to begin a new object morph.

- Frog force option
!frogForce ON/OFF – Administrator command
When enabled, normal Frog morphs automatically use the mutator’s custom Frog renderer. This exists as a workaround for the JJ2 large-level bug described earlier, where the player is correctly morphed into Frog internally but the game may continue displaying a stale Jazz or Spaz frame.
The mutator hides the incorrect native sprite and draws the Frog itself.

- !forcefrog – Player command
Forces your own Frog morph to use this custom renderer regardless of the automatic Frog Force behavior.

- Trace admin – Morph Menu option
!traceAdmin ON/OFF – Administrator command
Globally allows or disables the movement trace system. When disabled, traces are disabled for everyone.

PLAYER OPTIONS

- NyanRush option
!nyanrush ON/OFF – Player command
Enables or disables the integrated Nyan Rush visual replacement.
While Nyan Rush is active, it replaces the player’s normal character appearance.

- Old naming scheme option
!oldNamingScheme ON/OFF – Player command
Custom characters have very different heights and proportions. Player names are therefore normally repositioned vertically so they do not appear inside taller characters such as Lori or Devan.
Players who prefer JJ2’s original name positioning can enable the old naming scheme.

- Hang ledges local option
!hangLedgesLocal ON/OFF – Player command
Locally enables or disables ledge hanging for yourself while the server-wide Hang on ledges feature remains enabled.
This is particularly useful because ledge hanging can interfere with certain tests, movement exercises or situations in which a player does not want to grab a ledge unexpectedly.

- Trace feature option
!traceFeature ON/OFF – Player command
Determines whether you see the trace system at all.
A player who finds traces distracting can turn this OFF without preventing other players from using their own traces.

- Trace option
!trace ON/OFF – Player command
Enables or disables your own movement trace.
The trace system was inspired by weaponbunny.mut, but has been developed considerably further. When active, previous character frames remain briefly behind the player, creating an afterimage trail while running, jumping, performing special moves and falling.

The trace also has two additional color modes:
!trace rainbow – Creates a rainbow trace using red, orange, yellow, green, blue, indigo and violet. When the trace style is inverted, the rainbow order is reversed.
!trace random – Gives the individual afterimages randomly selected colors. Inversion reverses the order of the generated trace.

- Trace style – Morph Menu option
!invertTrace OFF – Normal graduated trace, with the shading progressing in its normal direction.
!invertTrace ON – Reverses the trace shading/order.
!invertTrace CONST – Uses one constant trace color instead of a graduated color ramp.
The Morph Menu cycles between these styles through the Trace style option.

- Trace color – Morph Menu option
!traceColor <0-255> – Sets the trace to any JJ2 palette index from 0 to 255.

For example:
!traceColor 24
uses palette index 24.

Common named colors are also available:
!traceColor red
!traceColor yellow
!traceColor green
!traceColor blue
!traceColor lime
!traceColor purple
!traceColor pink
!traceColor white
!traceColor black
!traceColor default

The Morph Menu’s Trace color option cycles through the predefined colors, while the numeric command provides access to the full JJ2 palette.

Rainbow and Random are separate trace modes rather than ordinary palette colors. The selected trace state, color, style and mode are synchronized so other players can see the intended effect.

Custom character sounds

There is a custom sound system as well. Supported characters can replace inappropriate Jazz or Spaz sounds with sounds belonging to the selected character, or suppress those sounds where no suitable replacement exists. This covers many ordinary gameplay events such as getting hurt, dying, jumping and performing special actions.

!useSilentSounds / !useSilentSoundboard – Enables or disables the custom character sound system.

The sounds themselves are provided in a separate downloadable JJ2 archive.

Having all of them download automatically from a server would be unwise. Apart from heavily increasing the loading time for players who do not already have the sound pack, the large number of characters means that there are roughly 100 individual sound files. JJ2 also has a download-file limit: if this mutator and other scripts together require more than 128 downloadable files, a joining client will be kicked with a “Bad request” error.

For this reason, players who want the custom sounds are strongly advised to download the sound archive separately rather than relying on server downloads.

Accessories

The character system also integrates my previous xmasHats.mut accessory system.

Players can wear not only hats, but also scarves/bowties and glasses. Each accessory can be selected or hidden independently, and supported colors can be altered using JJ2 palette shifts.

Hat graphics support separate color adjustment for red, yellow, black, blue and green areas. Scarves and glasses also support recoloring.

Accessory choices and colors are synchronized to other players and support individual local players in splitscreen.

Accessory commands

!hat / !hatN – Selects hat frame N.
!nohat – Hides your hat. !hat -1 may also be used.

!scarf / !scarfN – Selects scarf/bowtie frame N.
!noscarf – Hides your scarf/bowtie. !scarf -1 may also be used.

!glasses / !glassesN – Selects glasses frame N.
!noglasses – Hides your glasses. !glasses -1 may also be used.

Hat colors

!hatColorOffset / !hatColorOffsetRed – Changes the palette shift applied to the red portions of the hat.
!hatColorOffsetY / !hatColorOffsetYellow – Changes the yellow portions.
!hatColorOffsetBk / !hatColorOffsetBlack – Changes the black portions.
!hatColorOffsetB / !hatColorOffsetBlue – Changes the blue portions.
!hatColorOffsetG / !hatColorOffsetGreen – Changes the green portions.

Scarf and glasses colors

!scarfColorOffset – Changes the recolorable red portions of the scarf/bowtie.
!glassesColorOffset – Changes the recolorable red portions of the glasses.

!hatColorDebug – Displays the JJ2 palette indexes present in your current hat frame. This is mainly useful when creating or debugging recolorable accessories.

For splitscreen, an optional local player number from 1 to 4 can be added after the accessory command so that different local players can configure their accessories independently.

NOTE: The scarf and glasses features were added at the request of k10. I have adjusted the hat positions for the characters, but the scarf and glasses coordinates have not yet received the same adjustment work. As a result, scarves and glasses may not be positioned correctly for every character and animation yet.

Morph Menu – Page 4: Frog Hunt

The character system can also be used to play an optional custom game mode called Frog Hunt.

In Frog Hunt, some of the active players are randomly selected to become Witches, some may become Evas, and the remaining participants become ordinary bunny players.

The Witches’ objective is simple: turn all of the ordinary players into frogs before time runs out.

Eva acts as a support character for the players. Her kiss can revert a Frog morph, allowing her to rescue players whom the Witches have already transformed. The Eva count may also be set to zero; this can be useful on levels that already contain normal Eva objects, or simply if the server wants to play without a dedicated Eva player.

The Witches win immediately once there is no ordinary player remaining who is neither Eva nor Frog. If the timer reaches zero while at least one ordinary non-Eva, non-Frog player remains, the Players and Evas win.

Page 4 of the Morph Menu contains the following administrator controls:

!frogHuntSettings – displays the page directly.
Start / !frogHunt start – Starts a new Frog Hunt round. If the game is currently paused, Start instead resumes the existing round without assigning new roles.
Pause / !frogHunt pause – Pauses the Frog Hunt timer and also freezes the JJ2 game itself, keeping everybody in position.
Stop / !frogHunt stop – Aborts the current Frog Hunt round. If the game had been paused, normal JJ2 gameplay is resumed.
Time: < 5:00 > – Sets the round duration. Time changes in increments of 15 seconds, with a minimum of 1:00 and a maximum of 15:00.
Witches: < 2 > – Sets how many players become Witches. There must be at least one Witch. The maximum is based on the number of active players:
active players – 1 – Eva count
This guarantees that at least one ordinary player remains to be hunted.
Eva: < 1 > – Sets the number of dedicated Eva players. The minimum is 0 and the maximum is 3. If the chosen combination is impossible with the number of players currently in the server, it is adjusted when the round begins so that at least one Witch and one ordinary player remain.
The rest are players. – Every participant who is not selected as a Witch or Eva becomes an ordinary player.

When Frog Hunt begins, the mutator temporarily ensures that Witch and Eva use their special moves, regardless of their normal SPE/NORM configuration. Their previous settings are restored when the round ends or is aborted. Starting another Frog Hunt round resumes the game and assigns new roles.

While the Frog Hunt roles are normally assigned randomly, the server can enable Assignments to let players volunteer for the Witch or Eva roles before the round begins. A player can use !frogHuntMe witch or !frogHuntMe Eva to claim an available role on a first-come, first-served basis. Once all configured Witch or Eva positions have been claimed, further requests for that role are rejected. Any role positions that remain unclaimed are still filled randomly when the round starts. In splitscreen, an optional local player number can be added to the command. For example, !frogHuntMe witch 1 for the first local player or !frogHuntMe eva 2 for the second. Assignments are temporary: they are cleared after the round finishes, when Frog Hunt is stopped, or when the level cycles.

The Frog Hunt setup – time, Witch count and Eva count – is saved together with the other Morph Menu administrator settings.

Important implementation details

Animation usage
Each custom character’s frames are stored inside a single animation, with the mutator using frame indexes and mappings to interpret that animation as the many different actions the character needs.

This is a needed optimization because JJ2 has a limit of 1500 animations. If every action for every character were stored as an independent animation, a character pack of this size could eventually consume an enormous portion of that limit by itself.

Instead, each custom character consumes only a single animation for its packed character frames. The mutator determines which indexed frames correspond to running, jumping, shooting, standing, special moves and other actions. This means the mutator adds about 10 new animations, even though it adds a lot of new frames. However, the limit for the frames is 15000 and the possibility of reaching that is much lower.

Therefore, if JJ2 ever crashes because the 1500-animation limit has been reached while this mutator is running, the large custom-character roster itself should not be consuming hundreds of animation slots. Other loaded scripts and animation sets should also be inspected instead.

Multiplayer synchronization and performance
The multiplayer synchronization is designed around sending state changes rather than continuously transmitting character data every frame.

When a player’s important character state changes-such as morphing, changing size or entering Forced Frog mode-the mutator sends a compact character-state packet containing the relevant IDs and state values. Character packets also contain a session and revision number, so an older packet arriving late cannot overwrite a newer character state.

After an important local change, the same state is resent briefly as a reliability measure rather than being broadcast forever. The server also performs occasional full-state resynchronization so that a client which somehow missed an earlier update can correct itself later.

Monster and object morphs work similarly: the normal synchronization packet primarily needs the player ID and the selected monster/object index, with periodic server resynchronization used as a safeguard.

Trace synchronization sends the player’s trace settings-whether it is enabled, its color, style and color mode-rather than attempting to transmit a complete animated image every frame. Each client can then render the visual trail from the synchronized player state.

The result is that the mutator does not continually send the complete appearance of every custom character over the network. Most traffic is generated when something actually changes, with small reliability and periodic-resync mechanisms added to prevent players from becoming permanently desynchronized.

Saved settings
The main server configuration is stored in:
CustomCharactersSettings.asdat

This file saves the enabled/disabled state of each character morph, the selected custom-move mode for each character, and the principal server options such as Pregame only, custom sounds, Hang on ledges, Frog force, Trace admin, Hiding, Monster morphs and Object morphs.

This means that an administrator does not have to configure the character roster again every time the server or level is restarted.

Some personal preferences are stored separately so that they do not need to be mixed into the server-wide configuration. For example, CharsTrace.asdat stores the player’s Trace, Trace Feature, Trace color, Trace style, Trace mode and local ledge-hanging preference, while CharsNames.asdat stores the local name-positioning preference.
The normal character save system also retains character and fur information, while accessory selections and their color adjustments are saved by the accessory system.

Together, these systems are intended to make the mutator behave less like a temporary sprite replacement and more like a complete, persistent character framework for JJ2.

FAQ

1. Will new characters be added in the future?

Possibly, but creating a completely new custom character is very time-consuming. The last custom character I worked on took me about two weeks, spending roughly two to three hours on it after work each day. The work involves finding suitable sprites, deciding which frames correspond to each JJ2 animation, editing and sometimes redrawing them, converting them to the JJ2 palette, positioning them correctly, and finally implementing and testing the character in-game.

Because of this, I unfortunately cannot promise to create a new character simply from a request such as “please add this character to the pack.” However, if you already have the character’s animation frames prepared and adapted for JJ2 – or are willing to help with that part – then adding the finished character to the mutator becomes much more realistic, and I would be happy to consider it.

2. Can other accessories be added, such as dresses for Lori or pants for Spaz?

Not through the current accessory system, at least not in the same way as hats, scarves or glasses.

Hats, scarves and glasses are relatively static accessories. Their shape does not need to change dramatically from one animation to another. A hat, for example, generally remains on top of the character’s head; the mutator mostly needs to know where to position and rotate it for each frame.

Clothing such as pants, dresses, shirts or jackets would be very different. These are dynamic accessories: their shape would have to follow the character’s body, legs and pose during every animation. A dress would look completely different while Lori is standing, running, jumping, spinning or hanging from a helicopter, for example.

In practice, this would require drawing the clothing directly onto every relevant character frame. At that point it would essentially become a separate character set – such as “Lori with a dress” or “Spaz with pants” – rather than an accessory that can simply be attached to the existing character.

3. How to add new characters?

I may write a separate tutorial explaining how to prepare and edit character animations for JJ2, including the way animation frames need to be arranged for this mutator. Once that tutorial is ready, I will link to it here.

Special Thanks
Clank[NC] – for helping with a certain custom character and testing.
Zero[CDF] – for the frog ideas, the character heads idea, the bug reports, the testing and even implementation analysis.
FawFul and PurpleJazz – for the permission to include their characters into this mutator.
Violet and Seren – for help with better understanding JJ2 concepts back when I barely started angelscripting for JJ2.
K10-287[HsC] – for allowing me to use his NC Hotel server to test the mutator better in multiplayer
Fabian[NC] – for many of the ideas implemented in this mutator and encouragement.
Usagi[NC], Hëlgä[NC] – for testing, bug reporting and support.
And the whole NC clan – for being so kind and patient while this mutator was still incomplete and full of bugs.

If I have forgotten to mention anyone who helped me along the way, I sincerely apologize. The development of this mutator has stretched over a long period of time: I would work on it for a while, leave it aside, and return to it months later. I have done my best to remember and acknowledge everyone who contributed, tested, suggested ideas, reported problems, or otherwise helped shape it into what it is today.

I also kindly ask that you keep the scale of the project in mind when leaving feedback or reviews. This is a very large piece of work, developed and expanded over a long period of time. Although it has been thoroughly tested both by myself and by other players, there may still be minor bugs, unusual situations I have not encountered, or features that simply will not suit everyone’s preferences.

Constructive feedback and bug reports are always welcome, especially when they include enough information for me to reproduce the problem. I hope that, despite any small imperfections that may remain, you will enjoy the amount of variety and customization this mutator brings to JJ2.