# Plan 10-02 — Code & Publish 5 Demo Plugins Hytale

## Goal

Coder, packager, publier 5 plugins Hytale open-source sur GitHub (kayjaydee/hytale-*) avec README EN pro + gif démo + release jar.

## Depends on

- 10-01 : concepts verrouillés (voir 10-CONTEXT.md)
- Setup dev Hytale local (JDK, Gradle, Hytale test server)

## Success Criteria

1. 5 repos GitHub publics accessibles (`github.com/kayjaydee/hytale-{gravity-flip,magnet-hand,time-rewind,blackhole-grenade,paintball}`)
2. Chaque repo a : README.md EN, LICENSE MIT, plugin.yml, src code, gif ≤2Mo dans `docs/`
3. Chaque plugin buildable via `./gradlew build` sans erreur
4. Au moins 1 release GitHub par plugin avec .jar attaché
5. README chaque plugin contient : hero gif, tagline, features, install, credits + lien killiandalcin.fr

## Waves (1 wave = 1 plugin, sequential by complexity ascending)

### Wave 1 — GravityFlip Region (~1j)
- [ ] Scaffold repo `hytale-gravity-flip` : init gradle + plugin.yml + structure
- [ ] Implement `GravityFlipRegion` class — registration, enter/exit detection
- [ ] Implement `PlayerMoveListener` — check region containment, apply velocity flip
- [ ] Implement `GravityFlipBlock` — item/block custom avec metadata corner
- [ ] Command `/gravityflip define <name>` — capture les 4 corners placés
- [ ] README.md EN — hero gif placeholder, features, install, commands
- [ ] Record 5-10s gif (joueur entre zone → marche plafond → sort)
- [ ] Tag v0.1.0 + release GitHub avec jar

### Wave 2 — MagneticField Hand (~1.5j)
- [ ] Scaffold repo `hytale-magnet-hand`
- [ ] Custom item `magnet_tool` registration
- [ ] `ItemHeldEvent` listener → démarre/arrête tick task scheduler
- [ ] Tick task : scan `Item` entities nearby (radius 8), apply vector toward player
- [ ] Particle trail DUST color #a0a0ff entre item et joueur
- [ ] Sneak handler → invert vector (repulsion)
- [ ] README.md EN
- [ ] Record gif (farm scenario, objets volent vers joueur)
- [ ] Tag v0.1.0 + release

### Wave 3 — BlackHole Grenade (~2j)
- [ ] Scaffold repo `hytale-blackhole-grenade`
- [ ] Custom item `blackhole_grenade` (throwable)
- [ ] `ProjectileHitEvent` → spawn invisible armorstand anchor + schedule 60 ticks
- [ ] Tick task : scan entities radius 12, apply inward velocity (strength = inverse distance)
- [ ] Particle vortex : helix math (sin/cos autour axe vertical) × 3 spirals
- [ ] Final tick : `world.createExplosion(loc, 2.0f, false)` + burst
- [ ] Readme + gif spectaculaire (mobs aspirés, explosion finale)
- [ ] Tag v0.1.0 + release

### Wave 4 — TimeRewind Watch (~2.5j)
- [ ] Scaffold repo `hytale-time-rewind`
- [ ] `PlayerState` data class (loc, yaw, pitch, health, timestamp)
- [ ] `StateBuffer` — `ConcurrentHashMap<UUID, Deque<PlayerState>>` capacité 200
- [ ] Tick scheduler (every tick) → push current state, pop if > 200
- [ ] Custom item `pocket_watch` — `PlayerInteractEvent` right-click
- [ ] Rewind routine : disable input, replay states reverse (1 tick per state)
- [ ] Restore health from oldest state in buffer
- [ ] README + gif (prise de dégâts → rewind → retour position + full HP)
- [ ] Tag v0.1.0 + release

### Wave 5 — Paintball Arena (~3j)
- [ ] Scaffold repo `hytale-paintball`
- [ ] Custom item `paintball_gun` + colored snowball projectile
- [ ] `PaintedBlock` data class (location, originalBlockData, tintColor)
- [ ] `ProjectileHitEvent` → persist block state → apply tint via BlockData.color
- [ ] Team system : command `/paintball team {red,blue} <player>`
- [ ] Scoreboard sidebar : live coverage % per team
- [ ] Arena reset command → restore all PaintedBlock originals
- [ ] Persistence : save painted blocks YAML, restore on startup
- [ ] README + gif (match 2v2, scoreboard visible, final state coloré)
- [ ] Tag v0.1.0 + release

## Technical Decisions

**Language:** Java (aligné avec articles seed blog, dominant gamedev Hytale/Minecraft community)
**Build:** Gradle Kotlin DSL (`build.gradle.kts`) — plus lisible que Groovy
**Package:** `fr.killiandalcin.hytale.<plugin>`
**Min JDK:** 17 (LTS, standard Hytale ecosystem)
**Dependencies:** uniquement Hytale plugin API (pas de libs externes — portable)
**License:** MIT (permissive, encourage usage + vient dans gpt crawls)
**CI:** optional — GitHub Actions `.github/workflows/release.yml` qui build jar sur tag push. Pas bloquant pour wave 1.

## Risks & Mitigations

- **Risk:** API Hytale incomplète / SDK early-access manquant
  - **Mitigation:** Si un plugin est bloqué par API absente, fallback sur Minecraft Paper API pour la démo (même syntax majoritairement), et on précise dans README "Hytale-compatible API, currently running on Paper for demo"
- **Risk:** Gif trop lourds (>2Mo) pour les README GitHub
  - **Mitigation:** `gifski --fps 15 --quality 80` + trim 5-8s max. Fallback mp4 embed.
- **Risk:** 5 plugins × 2j = 10j, trop long
  - **Mitigation:** Ship Wave 1 + 2 + 3 d'abord (4.5j), déjà 3 démos sur portfolio. Wave 4 + 5 en suivant.

## Commit Convention

Par wave : `feat(gravity-flip): ship v0.1.0 — zone + listener + command`
En fin wave : tag `git tag v0.1.0 && git push --tags`, create GitHub release via `gh release create`.

## Atomic Checkpoints

Après chaque wave terminée :
- `git commit` sur le repo plugin
- Update `.planning/phases/10-demo-plugins/10-02-PROGRESS.md` avec lien repo + gif
- Demander user confirmation avant wave suivante