Support Jump Function with Parabolic Trajectory Movement

[zbrongyaozb]

Is it possible to support a jump function? Essentially, it still moves to a specified grid, but instead of moving in a straight line, it moves in a parabolic trajectory.

[Annoraaq]

If you need movement that is different from linear movement, I'd recommend disabling the sprite for the character and then use https://annoraaq.github.io/grid-engine/api/classes/GridEngineHeadless.html#getposition and https://annoraaq.github.io/grid-engine/api/classes/GridEngineHeadless.html#getmovementprogress to animate the movement of the sprite.

[zbrongyaozb]

If you need movement that is different from linear movement, I'd recommend disabling the sprite for the character and then use https://annoraaq.github.io/grid-engine/api/classes/GridEngineHeadless.html#getposition and https://annoraaq.github.io/grid-engine/api/classes/GridEngineHeadless.html#getmovementprogress to animate the movement of the sprite.

Hi @Annoraaq,

Thank you for your guidance! I have some follow-up questions regarding the implementation of the workaround you suggested, as I'm concerned it might conflict with Grid Engine's core movement logic.

1. Questions on getMovementProgress

From my understanding, getMovementProgress tracks the progress of a character currently moving via Grid Engine's movement system. This raises a few concerns for a "Jump" mechanic:

• Blocked Paths: If a character needs to jump over a "wall" tile to reach the ground below, standard movement would either be blocked or forced to take a long detour (e.g., finding stairs). In such cases, would getMovementProgress still function correctly if the character isn't technically "moving" through those blocked tiles?
• Multi-tile Jumps: If a jump spans across multiple tiles at once, does getMovementProgress support tracking the progress of the entire leap, or is it strictly limited to the progress between two adjacent tiles?

2. Proposal: "Virtual" or "Direct" Movement

Instead of a full parabolic implementation (which I understand involves complex collision and layer logic), would it be possible for Grid Engine to provide a "Virtual Movement" or "Leap" feature?

The idea would be:

• The user provides a start and end coordinate.
• Grid Engine performs a "logical move" that ignores standard tile collisions for that specific action.
• Grid Engine provides the movementProgress for this duration.

3. Importance of Internal State (isMoving)

The main reason I'm hoping for a solution within Grid Engine (rather than a purely external manual implementation) is State Management.

If I handle the jump entirely outside the engine by hiding the sprite and manual animating:

• gridEngine.isMoving(charId) will return false.
• I would have to update every part of my game logic from if (isMoving) to if (isMoving || myCustomJumpingState).

This makes the code much harder to maintain. Having a way to "tell" the engine that a character is in a special movement state (like jumping) would keep the API results like isMoving() consistent and reliable.

What are your thoughts on providing a lower-level "linear progress" move that allows us to handle the visual parabolic arc while the engine maintains the movement state?

[Annoraaq]

I understand. I think you can achieve this already with what GridEngine has to offer right now. In my opinion this jumping logic (basically allow to cross special blocking tiles under some circumstances) is already very particular to the individual game.

If you still want to use normal collisions but want to disable them under certain circumstances (player presses jump button), I would add an invisible character (no sprite) for each tile that contains a jumpable obstacle and give it a special collision group (like "jumpable"). Then give your character that same collision group. When the player presses the jump button you can remove that collision group from the character and initiate a movement and play your jumping animation: https://annoraaq.github.io/grid-engine/api/classes/GridEngine.html#setcollisiongroups

An alternative would be to allow to switch tile-collisions for characters on/off. Right now you can only set them when adding the character to GridEngine once. But I like the approach with the collision groups better, because it allows to distinguish between normal blocking tiles and jumpable ones.

[zbrongyaozb]

Hi @Annoraaq,

Thanks for the suggestions regarding collision groups! However, my main concern isn't really about how to handle collisions (which can be solved in several ways), but rather about Extensibility and State Integration.

I want to avoid a situation where my jumping logic is completely decoupled from Grid Engine's internal state. If I implement jumping entirely on the outside, I lose the benefits of built-in Observables like movementStarted$, movementStopped$, and positionChangeStarted$, and isMoving() would return incorrect values. Managing these states manually in parallel with the engine would make the game's architecture very messy.

Suggestion 1: Open up for Inheritance

To allow for custom movement logic while keeping the state machine intact, would you be open to exporting some of the internal classes and changing some private members to protected?
Currently, Grid Engine's architecture is quite closed for extension. Most internal implementation classes are hidden, and many critical properties are marked as private. This creates a significant barrier where it is almost impossible to extend logic via inheritance without forking the entire repository.

Specifically:

• For GridEngine.create: GridTilemapPhaser, GridCharacterPhaser
• For GridEngineHeadless.create: GridTilemap, GridCharacter

I understand that exporting internal classes usually requires documentation, but as a compromise to move things forward quickly, I’d be fine if they were exported without full documentation for now, as they are mostly for advanced use cases.

If this doesn't fit the current roadmap, I might have to fork the project to experiment with these changes. If the implementation becomes stable and generic enough later on, I’d be happy to discuss merging it back.

Suggestion 2: Plugin Mechanism

Alternatively, have you considered implementing a Plugin Mechanism?

This would allow users to register custom movement behaviors (like a "JumpPlugin" or "DashPlugin") directly into Grid Engine. This way, the engine could still manage the core movement state and lifecycle events, while the specific logic of how the character moves from A to B is handled by the plugin.

What are your thoughts on either of these paths to make the engine more flexible for custom movement behaviors?

[Annoraaq]

I want to avoid a situation where my jumping logic is completely decoupled from Grid Engine's internal state. If I implement jumping entirely on the outside, I lose the benefits of built-in Observables like movementStarted$, movementStopped$, and positionChangeStarted$, and isMoving() would return incorrect values. Managing these states manually in parallel with the engine would make the game's architecture very messy.

I am not sure I fully understand your concern here. If you use collision groups as described above, you could use GridEngines normal movement mechanic and just have a custom animation for jumping. The observables should work as expected. I think it is ok to have jumping decoupled from GridEngine as this is a non-supported game specific mechanic. What about flying, sliding, swimming, gliding etc? If added to GridEngine they become special cases for movement that must be considered for every change in the future which makes it overly complex. I'd rather keep GridEngine small and flexible enough so you can build your game specific logic around it.

There are some major downsides to opening up the API or creating a plugin system.
Creating a plugin system requires some careful thought and takes time to cleanly implement. Exposing internal classes and methods does not only require documentation (that is the lesser problem). It also makes future changes significantly harder (refactoring and new features) because everything that is exposed and therefore part of the API needs to be backward compatible. So it is a conscious design decision that the surface of GridEngine is as small as it is right now.

What would be an alternative is exposing some specific information that you are missing and why you need to use GridTilemap etc in the first place.

[zbrongyaozb]

Hi @Annoraaq,

Thank you for the detailed explanation. I completely understand your goal of keeping Grid Engine's API surface small for better maintainability.

However, I think there are two critical aspects where the suggested workaround (Collision Groups + Custom Animation) might not suffice for complex systems like an RPG Maker-style event interpreter:

1. Multi-tile and Diagonal Jumps

The "standard movement" in Grid Engine is tile-by-tile and linear. If a character needs to jump from (1,1) to (4,1) or jump diagonally:

• Pathfinding/Logic: Standard move commands treat this as a sequence of several horizontal steps. A "Jump" should ideally bypass the intermediate tiles' logic and collisions entirely in one single motion.
• Control Confirmation: If I use the move function, does Grid Engine support a mode where the character's logical state is "moving," but I have 100% control over the Sprite's position during that transition without the engine trying to snap the sprite to its own calculated linear path?

2. The Necessity of Consistent Signals (isMoving/Observables)

My project is a reactive event interpreter. In this architecture, isMoving and Observables like movementStarted$ are not just for animations—they are global synchronization signals for other decoupled systems (e.g., parallel event triggers).

If I implement jumping externally:

• State De-sync: isMoving() returns false during the jump. This causes "Parallel" or "Autorun" events to trigger incorrectly because they perceive the character as idle.
• Signal Failure: Other systems waiting for movementStopped$ will trigger too early or not at all.

A Potential Alternative: "Manual Movement Mode"

Since you prefer not to expose internal classes, would it be feasible to expose a lightweight way to trigger a movement state without the engine's default linear pathing?

Something like: gridEngine.startExternalMovement(charId, targetPos).
This would:

1. Set isMoving to true.
2. Fire the standard movement Observables (movementStarted$, etc.).
3. Let Grid Engine manage the movement progress based on the character's speed attribute, but without updating the sprite's X/Y position.
4. Fire movementStopped$ once the logical movement to targetPos is completed.

This would keep the engine's surface small while allowing developers to implement custom movement (flying, jumping, sliding) while staying perfectly in sync with Grid Engine's state management.

What do you think of this "state-only" movement approach?

[zbrongyaozb]

What would be an alternative is exposing some specific information that you are missing and why you need to use GridTilemap etc in the first place.

Hi @Annoraaq,

To answer your question about why I specifically need access to those internal classes: it's because I currently have to resort to "monkey-patching" Grid Engine's core logic to support the specific collision mechanics of RPG Maker MZ.

1. Why those 4 classes?

I mentioned GridTilemapPhaser, GridCharacterPhaser, GridTilemap, and GridCharacter because they are the core components instantiated within the create methods of GridEngine and GridEngineHeadless. Since these methods and their resulting instances are private, I cannot extend or replace them with custom logic without access to these class definitions.

2. Real-world example: Collision Logic Overhaul

My project uses maps converted directly from RPG Maker MZ, which uses a completely different collision philosophy compared to Grid Engine:

• Grid Engine: Uses a bottom-up physical layer approach. If there is a bridge over water, GE might detect the "water" tile first and block movement unless complex layer transitions are configured.
• RPG Maker MZ: Uses a top-down visual approach. If the top-most visible tile (the bridge) is passable, the character moves, regardless of what's underneath.

Because I cannot extend GridTilemap, I had to implement a fragile patch to override hasBlockingTileUncached like this:

// Forcing access to private constructor to patch prototype
GridTilemapClass = gridEngineInstance._gridTilemap.constructor as Type<GridTilemap>;
const proto = GridTilemapClass.prototype as GridTilemap;
this.originalHasBlocking = proto.hasBlockingTileUncached;

proto.hasBlockingTileUncached = function (pos, charLayer, direction, ignoreHasTile) {
    if (this.isRMMap) {
        // Custom RPG Maker top-down collision logic here
    } else {
        return originalHasBlocking.call(this, pos, charLayer, direction, ignoreHasTile);
    }
};

[Annoraaq]

2. The Necessity of Consistent Signals (isMoving/Observables)

You should create wrapper observables that take the jumping state into account for your state management. That is simpler and more flexible than adapting GridEngines core to your needs. Better adapt GridEngines observables to your specific game logic.

My project uses maps converted directly from RPG Maker MZ

Instead of exposing internal classes you can write a tool that transcodes RPGMaker Maps to a format that is compatible with GridEngine. Tilemap is only an interface (https://annoraaq.github.io/grid-engine/api/interfaces/Tilemap.html). So you can write your own version that is more compatible to the RPG maker one.

[zbrongyaozb]

Thank you for the detailed feedback. I would like to address your two points separately with more technical context.

1. Goal: Unified Management of Internal Movement States

Regarding the suggestion to use wrapper observables: managing a "jump" state is NOT my primary goal. My core requirement is the ability to natively manage all movement-related states within Grid Engine.

• The Problem with Wrappers: If I implement an external wrapper, Grid Engine's internal state (like isMoving) remains out of sync. This forces me to either:
  1. Access and modify GE's private properties to force state updates.
  2. Apply fragile monkey-patches to ensure GE's internal logic and external signals match.
• Necessity of Native Support: Without native hooks to manage these states, any decoupled system relying on GE's status (like NPC avoidance or parallel event triggers) will behave unpredictably. I need GE's "Source of Truth" to reflect the actual state of the character, whether it's a standard move, a jump, or a custom event-driven movement.

2. Map Mechanics: Why Transcoding to GE Paradigm is Counterproductive

Regarding the map structure and the Tilemap interface: while I am transcoding maps, a full conversion to GE's native paradigm is practically impossible due to the unique way RM MZ handles tiles:

• The Proxy Core Logic: I use a Proxy for Phaser.Tilemap that overrides getTileAt. Since RM MZ dynamic tiles (autotiles) are composed of four 24x24 mini-tiles, my Proxy logic intercepts getTileAt to find these mini-tiles and map them back to the collision attributes of the original 48x48 "big tile".
• The Coordination: This allows me to "trick" Grid Engine into operating on a 48x48 coordinate system while Phaser renders the 24x24 tiles correctly. Rendering and collision are already working through this method.
• The Paradigm Conflict: The real issue is that RM MZ uses a Top-Down Visual Passability logic, whereas GE uses a Layer-based Transition logic.
• The "Counterproductive" Barrier: To fully adapt RM maps to GE's native layer system, I would have to discard RM's original logic and reinvent GE-specific layer switches (a concept that doesn't exist in RM). This is counterproductive; my goal is to build an interpreter that runs RM projects with zero modifications.

[Annoraaq]

Grid Engine's internal state (like isMoving) remains out of sync.

That is why I suggest to not rely on this property in your game but instead create your own isMoving that takes GridEngine plus jumping logic into account.

Without native hooks to manage these states, any decoupled system relying on GE's status (like NPC avoidance or parallel event triggers) will behave unpredictably.

Yes. Every part of your game should use your game specific state and not GridEngines when it wants to take jumping into account. But that is a logical consequence of GridEngine having no concept of jumping. And I am not convinced that adding this concept would be benefitial to more than a specific use case (jumping can be implemented in several different ways).

Map Mechanics: Why Transcoding to GE Paradigm is Counterproductive

Grid Engine has its own logic for map layers and collision layers. RPG maker might have a different one. But it is not Grid Engines responsibility to be compatible to RPG Maker.

I see 2 ways we could address "custom collisions" that do not adhere to the GridEngine collision logic:

1. We make a function part of the TileMap interface that checks for a collision. So you can pass your own logic for that. No monkey patching or exposure if internal classes needed.

2. You create a "transcoder" that takes the rpg maker map and creates a new tile layer that contains all the collisions. Basically a collision layer as explained here: https://annoraaq.github.io/grid-engine/p/collision-layers/

[zbrongyaozb]

Hi @Annoraaq,

Thank you for the response. I'd like to dive deeper into the architectural implications of "external state management" and why I believe a more integrated approach is necessary.

1. The Cost of "Parallel States" (isMoving & Observables)

You suggested creating a wrapper for isMoving. However, the concern isn't just a single boolean. Grid Engine provides a rich reactive ecosystem: movementStarted$, movementStopped$, positionChangeStarted$, positionChangeFinished$, etc.

If I implement custom movement (like jumping) externally:

• Redundancy: I would have to recreate and manually trigger every single one of these observables in a wrapper. This essentially means rewriting Grid Engine's state machine outside of the engine.
• Internal De-sync: If I use a wrapper, GE's internal logic remains "blind" to the movement. If I have to choose between maintaining two "parallel truths" or "hacking" into private Subjects to fire events, the latter is actually safer for long-term consistency because it ensures GE's internal state stays aligned with the actual game situation.

2. Cosmetic Logic vs. Displacement Logic (The Lighting Analogy)

I agree that some logic is perfectly suited to be implemented independently of Grid Engine. For example, playing footstep sounds or displaying footprints. These are purely cosmetic; they don't affect the character's position or the engine's core flow, so decoupling them makes total sense.

However, displacement (whether it's a standard walk, a jump, or a dash) is fundamentally different. Because Grid Engine already owns and manages the positional attributes and movement events, any logic involving coordinate changes must be integrated.

Think of it like wiring a house:

• Cosmetic (Decoupled): Hanging a picture on the wall doesn't require touching the house's electrical grid.
• Displacement (Integrated): Installing a new light (a jump or dash mechanic) should plug into the existing electrical grid so it works with the main switches and breakers (GE's state/events).
• The Conflict: Telling a developer to "manage their own state" for displacement is like saying, "The house wiring is closed; you must install a separate solar panel just to power that one light." It's inefficient and leads to a fragmented, unmaintainable system.

I believe GE should provide a "Logical Movement Mode" where GE manages the state, progress, and events, while the user manages the visual trajectory.

3. Custom Collision Logic (TileMap Interface)

Regarding your options for collisions:

• Option 1 (Adding a check function to the TileMap interface): This is an excellent solution. If the TileMap interface includes a method like hasBlockingTile(pos, layer, direction), I can implement RM MZ's top-down passability logic there cleanly without monkey-patching or exposing internal classes. This solves the "Collision Paradigm" conflict perfectly.
• Option 2 (Transcoder/Collision Layers): This is less feasible. RM has complex context-sensitive collisions (e.g., a boat passing on water where a player cannot). Managing this solely through static layers would lead to a data explosion and still require workarounds for dynamic changes.

Summary

I am very much in favor of Option 1 for collisions.

For movement, I strongly suggest providing a hook into the internal state machine. If GE can handle the "logical" tile-to-tile transition while letting the user control the sprite's visual path, it would ensure architectural consistency for any game that goes beyond basic walking.

[Annoraaq]

Ok option 1 sounds good.

For movement, I strongly suggest providing a hook into the internal state machine. If GE can handle the "logical" tile-to-tile transition while letting the user control the sprite's visual path, it would ensure architectural consistency for any game that goes beyond basic walking.

GridEngine handles the logical tile to tile transition already. It is just a movement. As I suggested in my first response, you can use your own sprite (do not attach it to GridEngine) and then do whatever animation you want with it (control the visual path as you phrased it). You can have your own trigger conditions for this type of animation.

What exactly are you missing from GridEngine that would make things easier?

[zbrongyaozb]

GridEngine handles the logical tile to tile transition already. It is just a movement. As I suggested in my first response, you can use your own sprite (do not attach it to GridEngine) and then do whatever animation you want with it (control the visual path as you phrased it). You can have your own trigger conditions for this type of animation.

Hi @Annoraaq,

I think I understand your suggestion better now. I could add a character without a sprite to GridEngine to handle the logic. However, I see some technical challenges regarding the implementation, specifically for non-8-directional movements:

1. Limitation of 8-Directional Movement

For simple straight or diagonal jumps, converting tile-by-tile progress to a global progress is manageable. However, the problem arises with arbitrary targets—for example, a jump that moves 3 tiles right and 4 tiles up.

• The Jump Logic: A jump is always a straight visual line from A to B.
• The GE Logic: Currently, GridEngine only supports 8-directional movement.
• The Solution: If GridEngine could be extended to support linear movement between any two arbitrary points, it would solve my problem perfectly. Is this something you would consider adding?

2. Difficulty in Progress Mapping and Path Predictability

If I use moveTo() to drive the logic, I face a "Black Box" pathing issue. To accurately map GE's logical progress to my visual jump progress, I need to know the exact path and the total logical distance:

• Path Uncertainty: If GE decides to move 3 tiles right and then 4 tiles up, the path is different than 4 up then 3 right. Without knowing the exact sequence of tiles in advance, I cannot pre-calculate the mapping for the visual linear progress.
• Total Distance Calculation: Does GridEngine provide a way to retrieve the planned path after calling moveTo()? If not, I would have to manually track every step taken (detecting if it was a straight or diagonal move) to calculate the cumulative progress.
• Alternative: To make the path deterministic for my math, I would likely be forced to use addQueueMovements() instead of moveTo(), which adds significant overhead to the implementation.

3. Feasibility of Sprite Swapping

Even if the math is handled, I need to confirm the practical implementation of swapping sprites:

• The Workflow: When a special movement starts, I would need to remove the normal sprite and attach a transparent one. Once the movement finishes, I would swap the normal sprite back.
• Constraint: The GridCharacter must not be destroyed or re-created during this process to maintain event listeners and state management.

Does GridEngine currently provide a clean, reliable way to swap or detach/re-attach sprites to an existing GridCharacter without internal side effects? If this process is too complex or prone to issues, this workaround might not be a viable solution for a production-ready system.

I’d love to hear your thoughts on whether arbitrary linear movement or a stable sprite-swapping mechanism is feasible.

[Annoraaq]

1. Limitation of 8-Directional Movement

It is currently not planned to provide a linear movement to a non-neighboring field. You have to use setPosition for this.

2. Difficulty in Progress Mapping and Path Predictability

You can use pathfinding to get the path in advance and then move along that path via queued movement

3. Feasibility of Sprite Swapping

I would add another sprite and when "swapping" just toggle the visibility of the two.

[zbrongyaozb]

Thanks! It seems there are no more blockers for now. I'll give it a try.