feat: implement Turn-Based RPG Arena with status effects and cooldown systems

[salazarsebas]

Context

Cougr would benefit from an example focused on turn-based combat with richer state transitions than current arcade or board examples. A small RPG arena is a good fit because it introduces cooldowns, status effects, and action resolution while remaining deterministic and testable.

Goal

Create examples/rpg_arena/ as a standalone Soroban smart contract example that implements a compact turn-based combat loop.

The example should support two combatants, a small action set, status effects, cooldown tracking, and match resolution.

Scope

In scope:

• smart contract logic only
• deterministic two-combatant battle
• actions such as attack, defend, and one special ability
• status effects and cooldowns
• win detection
• README and CI workflow

Out of scope:

• exploration, inventory, quests, or narrative systems
• graphical UI
• matchmaking or progression economy

ECS Design Direction

Suggested components:

Component	Fields	Purpose
CombatantComponent	hp, defense, speed or equivalent	Stores battle stats
StatusEffectComponent	effect_kind, duration, magnitude	Tracks active statuses
CooldownComponent	action_kind, remaining_turns	Tracks ability reuse
TurnComponent	current_actor, round	Tracks flow
BattleStatusComponent	status	Tracks ongoing or finished match

Suggested systems:

• ActionValidationSystem
• DamageResolutionSystem
• StatusEffectSystem
• CooldownSystem
• TurnAdvanceSystem
• EndConditionSystem

Contract API

fn init_battle(env: Env, player_one: Address, player_two: Address)
fn submit_action(env: Env, player: Address, action: Action)
fn get_state(env: Env) -> BattleState
fn get_combatant(env: Env, player: Address) -> CombatantState
fn is_finished(env: Env) -> bool

Tests

Add tests covering:

• initialization
• basic attack resolution
• defend interaction
• special ability cooldown handling
• status effect application and expiration
• wrong-turn rejection
• battle completion

Deliverables

• examples/rpg_arena/
• contract implementation and tests
• examples/rpg_arena/README.md
• .github/workflows/rpg_arena.yml

Acceptance Criteria

• the combat loop is deterministic and testable
• cooldowns and status effects behave correctly
• turn order and end conditions are enforced correctly
• the example demonstrates clean Cougr-style decomposition
• documentation and commands use wasm32v1-none

Validation Commands

cd examples/rpg_arena
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
stellar contract build

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[Owolabenjade]

@Owolabenjade has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hi Maintainer, I would like to work on this issue, kindly assign me. I'm an experienced Rust developer and I can have a PR up within a couple of hours.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Owolabenjade to this issue.

[drips-wave]

Congratulations, @Owolabenjade! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @Owolabenjade: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊