Jazz Jackrabbit 2 Online

Please read the following description before using this.

The basic story behind this mutator is that I wanted an onHurt hook, but that doesn't exist in the API. There doesn't seem to be a straightforward way to check for collisions in the current API either, but whipping that up was easier than a theoretical onHurt, so thus the birth of this mutator, good enough.

This mutator isn't really meant to be used standalone. Rather, it's meant to be used as a library. A simple example of this is in player_collision_example.mut. Only player_collision_detector.mut and player_collision_detector_header.asc are needed if you plan to use it.

———

COLLIDE::getDetector() returns the object where you can interact with the detector. If your plus.ini file contains the line AngelscriptDebug=True under [General] then messages will be logged to your chatlog window if the function fails for whatever reason.

• void setHook(COLLIDE::HOOK@ hook = onCollide, uint moduleID = jjScriptModuleID)
  Sets a function to be called whenever a player collides with another player. The function signature assumes you've (probably) already defined a global function called onCollide, so you don't need to pass any arguments when calling it. If you'd prefer to provide a different function, then call setHook(myFunc) with myFunc being your function. The second parameter, which defaults to your distinct script module's ID, is how the detector keeps track of multiple hooks from different scripts. It's best to let the default argument handle it and avoid passing in a different ID; otherwise, you may introduce some interesting behavior.

• void unsetHook(uint moduleID = jjScriptModuleID)
  Removes the function that was provided from setHook by a script associated with the given moduleID. By default, this is the same script where you would call setHook.

It is important to note that the methods described above only apply to the local player. This does not matter if you use them in a hook that is called for all players (e.g., onLevelLoad, onLevelBegin), but if these are not your use cases then you must consider this. On the other hand, the methods listed below will affect all players:

• void startDetecting()
  Allows players to have onCollide be called whenever a collision occurs.

• void stopDetecting()
  Stops onCollide from being called whenever a collision occurs.

———

Any function can be passed as the first argument to setHook as long it has the signature void function(jjPLAYER@ victim, jjPLAYER@ collider, COLLIDE::Collide collision, uint8 eventID) The first two parameters are self-explanatory. The third parameter is the type of collision that gets passed in as an argument. Possible values are:

• COLLIDE::BULLET (Caused by a weapon with damage 1)
• COLLIDE::BULLETPU (Caused by a weapon with damage 2)
• COLLIDE::BUMP (Caused by a player bumping onto another player)
• COLLIDE::STOMP (Caused by a player buttstomping)
• COLLIDE::SUGARRUSH (Caused by passing through another player while on sugar rush)
• COLLIDE::SPECIALMOVE (Caused by a player doing a special move through another player, like Spaz's karate kick for example)

The fourth parameter, if collision is COLLIDE::BULLET or COLLIDE::BULLETPU, is the event ID of the bullet that collided with the victim player. This value may be useful, especially if passed as an argument to the function:
jjOBJ@ COLLIDE::getProbableBulletAccordingToThisCollision(const jjPLAYER@ victim, const jjPLAYER@ collider, uint8 eventID)
Since onCollide gives you access to victim, collider, and eventID, it's only natural to pass them as arguments to the above function. The function returns a jjOBJ@ that is likely the bullet that collided with the victim. Note the emphasis on likely since the function cannot guarantee it's the same bullet (or that it even returns non-null at all!) since all objects are copies for each client. This function isn't very useful outside of onCollide but you're technically allowed to do that.

———

Change Log:

May 2, 2025 2 AM UTC (starting with this upload)
- Bullet detection no longer relies on overriding their default behavior. This means custom weapons should be less broken now.
- Reduced amount of packets being sent to update a player's buttstomp/special move status.
- Reduced amount of packets being sent to trigger onCollide for buttstomp, special moves, and bumps.
- Made bump collision detection a bit more accurate by accounting for directions, speed, and ignoring blinking players.
- Bump collision detection is now done at the bumper's side instead of the bumped's side.
- Fixed secondary detection incorrectly relying on rabbit animations for frog and bird players.
- New parameter added to onCollide: eventID. If a collision comes from a bullet then this is set to its corresponding OBJECT::Object constant. The value has no meaning if the collision stems from player movements.
- New experimental function added: jjOBJ@ COLLIDE::getProbableBulletAccordingToThisCollision(const jjPLAYER@ victim, const jjPLAYER@ collider, uint8 eventID) – to be used inside onCollide. See above description for more details.
- Separated COLLIDE::STOMPORRUSH to COLLIDE::STOMP and COLLIDE::SUGARRUSH

Apr. 12, 2025 1 AM UTC
- The detection algorithm was revamped to do a second check after a potential region of collision is detected. This second check relies on a timeout mechanism, which should catch more cases than the previous versions, but that's not fully guaranteed.

Apr. 11, 2025 5 PM UTC
- Splitscreeners now supported.

Mar. 14, 2025 4 AM UTC
- Bullet detection no longer uses onObjectHit as this caused issues with some objects overriding their own default behavior. The drawback of this is that if the player being shot is not an enemy, the detection will be less accurate.

Mar. 1, 2025 4 PM UTC
- Fixed a potential issue with RF bullets.

Feb. 19, 2025 10 PM UTC
- Fixed bugs that caused some weapons to be in an infinite exploding state and Gun8 not firing for the local player.

Feb. 19, 2025 6 AM UTC
- First release

The JJ2+ devs implementation of AngelScript for allowing me to come up with this abomination.