# HeartBeast Action RPG

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

```{raw} html
<a class="example-run-button" href="../demos/ports_heartbeast_rpg.html">▶ Run in browser</a>
<p><strong>Upstream:</strong> <a href="https://github.com/uheartbeast/godot-action-rpg-tutorial">https://github.com/uheartbeast/godot-action-rpg-tutorial</a></p>
```

**Tags:** `port` `tier-2`

# HeartBeast Action RPG: SimVX Port

Tier 2 port #18 of [uheartbeast/godot-action-rpg-tutorial](https://github.com/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

```bash
# 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

```bash
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.

## See also

- `NOTES.md`: porting friction, engine gaps, BUGS.md cross-refs
- `../PORTS.md`: master port list
- `../../simvx/CLAUDE.md`: engine rules


## Source

```{literalinclude} ../../examples/ports/heartbeast_rpg/main.py
:language: python
:linenos:
```