portfolio/.planning/phases/10-demo-plugins/10-02-PLAN.md

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