HeartBeast Action RPG¶

The canonical Godot tutorial port, sword + roll + enemies.

Upstream: https://github.com/uheartbeast/godot-action-rpg-tutorial

Tags: port tier-2

HeartBeast Action RPG: SimVX Port¶

Tier 2 port #18 of uheartbeast/godot-action-rpg-tutorial.

What it is¶

A faithful port of the canonical HeartBeast Godot Action RPG tutorial to SimVX. Implements the complete combat loop: player movement with acceleration/friction, directional sword attacks, roll/dodge with invincibility frames, enemy AI with Idle→Wander→Chase state machine, soft collision between enemies, destructible grass, and a heart-based HUD.

Running¶

# From /home/fezzik/dev/simvx:
uv run python ../ported_games/heartbeast_rpg/simvx_port/main.py              # desktop
uv run python ../ported_games/heartbeast_rpg/simvx_port/main.py --test       # headless smoke
uv run python ../ported_games/heartbeast_rpg/simvx_port/capture.py           # screenshots

Controls¶

Action	Keys
Move	W/A/S/D or Arrow Keys
Attack	J, Z, or Left Mouse
Roll/Dodge	K or X
Quit	Escape

Architecture¶

nodes/
├── camera.py      Bounded Camera2D with world clamping
├── effects.py     HitEffect, EnemyDeathEffect, GrassEffect (auto-destroy)
├── enemy.py       Bat enemy with Idle/Wander/Chase FSM + soft collision
├── grass.py       Destructible grass patches
├── hud.py         Heart-based health bar overlay
├── player.py      Player: movement physics, sword, roll, invulnerability
├── stats.py       Signal-based health tracker (mirrors upstream Stats.tscn)
└── world.py       Main scene: tilemap, entities, collision dispatcher

Feature parity with upstream¶

Feature	Status	Notes
Player movement (accel/friction)	✅	Matches upstream speed values
8-directional movement	✅	Normalised diagonal
Sword attack with rotation	✅	Hitbox follows movement direction
Roll/dodge with i-frames	✅	0.3s duration, 250 px/s
Enemy AI (Idle/Wander/Chase)	✅	3-state FSM with detection radius
Soft collision	✅	Push-apart between overlapping enemies
Destructible grass	✅	20 patches, effect on destruction
Invincibility frames + flash	✅	Blink effect for both player and enemies
Health system (signals)	✅	Stats node with health_changed/no_health
Heart-based HUD	✅	6 hearts, updates via signals
Bounded camera	✅	Clamped to world edges
Death/respawn	✅	2s delay, full health restore
Hit/death/grass effects	✅	Particle burst, auto-destroy
Tree/Bush decorations	✅	Procedural draw
Audio	⬜	SFX not included (licensing)
Animation (sprite flip)	✅	Wing flap simulation
Tilemap terrain	✅	Procedural grass + dirt path

Web Export¶

cd /home/fezzik/dev/simvx
uv run simvx export web ../ported_games/heartbeast_rpg/simvx_port/main.py \
    -o ../ported_games/heartbeast_rpg/simvx_port/web/index.html

Output: web/index.html (~2613 KB), auto-detects GameRoot, no extra flags needed.

License¶

Upstream tutorial code by uheartbeast (Godot co-creator) is CC0/MIT. Assets (HeartBeast pixel art, OpenGameArt music) are NOT bundled; this port uses procedural rendering for all visuals. Audio is stubbed for licensing compliance.

Source¶

#!/usr/bin/env python3
"""HeartBeast Action RPG: The canonical Godot tutorial port, sword + roll + enemies.

# /// simvx
# tags = ["port", "tier-2"]
# upstream = "https://github.com/uheartbeast/godot-action-rpg-tutorial"
# web = { width = 1280, height = 720, responsive = true }
# ///

Canonical Godot tutorial port: top-down ARPG with player movement,
sword combat, roll/dodge, enemy AI with state machines, health system,
invincibility frames, soft collisions, and grass destruction.

Run:
    uv run python ported_games/heartbeast_rpg/simvx_port/main.py
    uv run python ported_games/heartbeast_rpg/simvx_port/main.py --test
"""
from __future__ import annotations

import argparse
import sys
from pathlib import Path

# Allow flat sibling imports (settings, nodes.*)
_PORT_DIR = Path(__file__).resolve().parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from simvx.core import InputMap, Key, MouseButton, Node2D
from simvx.graphics import App

from nodes.world import World
from settings import HEIGHT, WIDTH, INPUT_ACTIONS


# Key name → Key enum mapping (avoids reflection)
_KEY_MAP = {
    "w": "W", "a": "A", "s": "S", "d": "D",
    "j": "J", "k": "K", "z": "Z", "x": "X",
    "up": "UP", "down": "DOWN", "left": "LEFT", "right": "RIGHT",
    "escape": "ESCAPE",
}


class GameRoot(Node2D):
    """Root scene node: registers input actions then loads the world."""

    def on_ready(self):
        from simvx.core import Key, MouseButton

        for action, keys in INPUT_ACTIONS.items():
            bindings = []
            for k in keys:
                if k == "mouse_left":
                    bindings.append(MouseButton.LEFT)
                else:
                    enum_name = _KEY_MAP.get(k.lower(), k.upper())
                    bindings.append(getattr(Key, enum_name))
            InputMap.add_action(action, bindings)

        self.add_child(World())

    def on_process(self, dt: float):
        from simvx.core import Input
        if Input.is_action_just_pressed("escape"):
            self.app.quit()


def main():
    parser = argparse.ArgumentParser(description="HeartBeast Action RPG")
    parser.add_argument(
        "--test", action="store_true",
        help="Headless smoke run, exit after a few frames."
    )
    args = parser.parse_args()

    if args.test:
        app = App(width=WIDTH, height=HEIGHT, title="HeartBeast RPG (test)", visible=False)
        frames = app.run_headless(GameRoot(), frames=30)
        print(f"OK: rendered {len(frames)} frames headlessly")
        return

    App(width=WIDTH, height=HEIGHT, title="HeartBeast Action RPG").run(GameRoot())


if __name__ == "__main__":
    main()