Skip to content

Latest commit

 

History

History
58 lines (52 loc) · 13.3 KB

CLAUDE.md

File metadata and controls

58 lines (52 loc) · 13.3 KB

CLAUDE.md — Java-MightyLibrary

Moteur de jeu 2D/3D en Java 11 (LWJGL 3.3.6, OpenGL 3.3 core, GLFW, OpenAL, STB, Assimp ; JOML, org.json, JBox2D). src/io/github/mightycode/mightylib = la bibliothèque, src/io/github/mightycode/mightylibdemo = la démo qui sert de banc d'essai. Objectif : en faire une bibliothèque réutilisable (jar) pour les futurs jeux et logiciels de l'utilisateur.

Documentation (à lire seulement quand la tâche le demande)

  • docs/current.md : seul le gros point en cours (philosophie du moteur : rendu extensible, point d'injection, systèmes de l'Engine injectables, repli GL, héritage et API publique, démo en module Maven séparé ; un /planification-ml par objectif).
  • docs/later.md : comment écrire current.md (but, cycle de vie, format), puis feuille de route globale, gros points suivants dans l'ordre (gamma, tests, bibliothèque réutilisable et modding, effets 2D, physique 2D, entités et scripts Lua, thème, rendu 2D, SVG, entrées, son, console, plateformes).
  • docs/techniquegraphique.md : suite de later.md, techniques de rendu 2D/3D de LearnOpenGL (Blinn-Phong, skybox, culling, ombres, normal mapping, animation squelettique, HDR/bloom…).
  • docs/futur-discussion.md : sujets à discuter un jour, sans ordre (l'utilisateur décide quand).
  • licence.md : licences de toutes les dépendances, des bibliothèques natives et des ressources, ce qu'elles impliquent, à faire avant distribution (à mettre à jour à chaque nouvelle dépendance ou ressource).
  • docs/decisions.md : décisions de conception durables (pas de Lombok, package network conservé…).
  • docs/architecture.md : structure, démarrage, boucle, cycle de vie des scènes, ressources CPU/GPU, rendu, entrées, temps, pièges connus.
  • docs/debug-tools.md : commandes, serveur de debug, simulation d'entrées, traque des fuites, profilage (JFR, RenderDoc).
  • docs/bonnes-pratiques.md : points que le projet doit respecter, chacun avec sa vérification ; revue hebdomadaire à la demande de l'utilisateur (skill /revue-pratiques).
  • docs/plan/ : plans des gros points en cours d'implémentation (un fichier par sujet, écrit par /planification-ml, supprimé à la fusion de la PR qui le réalise).
  • Skills du projet (.claude/skills/) : /revue-pratiques, /analyse-intellij (warnings exportés d'IntelliJ ; pour Error Prone et SpotBugs : python tools/analyse.py, voir docs/debug-tools.md), /implement-next-objective [objectif] (implémente la prochaine ligne de current.md si elle est assez petite, sinon renvoie vers /planification-ml ; s'arrête avant la PR), /pr-ml [branche] (relecture du diff par rapport à dev, erreurs discutées puis corrigées, docs, PR GitHub fusionnée, retour sur dev à jour), /planification-ml <sujet> (discussion en questions-réponses, plan dans docs/plan/, commandes des discussions d'implémentation et de /pr-ml).

Priorités

  • La 2D est prioritaire (rendu 2D, tilemaps, texte, GUI, Camera2D, animations, physique 2D).
  • La 3D est secondaire : ne pas l'étendre ni la refactorer sans demande, mais ne pas la casser (Shape/Renderer/Shader sont communs ; les scènes 3D Scene3D, Scene3DBis, Game3D2D et TerrainGeneration3D doivent rester fonctionnelles).

Build et vérification

  • Maven avec sourceDirectory = src, tests JUnit 5 dans test/ (mêmes packages que le code testé, pour accéder au package-private). Compiler après chaque modification :
    • Linux : mvn/java (JDK 21) sont dans le PATH : mvn -o -q compile.
    • Windows : mvn/java ne sont pas dans le PATH, utiliser les outils d'IntelliJ :
      JAVA_HOME="$HOME/.jdks/ms-21.0.9" "/d/Program Files/JetBrains/IntelliJ IDEA Community Edition 2024.2.3/plugins/maven/lib/maven3/bin/mvn" -o -q compile
    • Tests : même commande avec test au lieu de compile (quelques secondes, sans fenêtre ni GL).
    • scenario.py choisit ces chemins selon l'OS (surchargeables par MIGHTY_JAVA, MIGHTY_MVN, MIGHTY_MAVEN_JDK). Sur une nouvelle machine, lancer une fois mvn -q compile (sans -o) pour télécharger les dépendances.
  • Tests automatisés, à chaque modification : se demander si elle touche du code couvert par les tests (aujourd'hui : resources/, graphics/GLResources (dont l'état d'échec des éléments et leur remise en file par dataReloaded), graphics/shader/ShaderPreprocessor (#include, #line, traduction du journal), graphics/text/FontFile, graphics/text/DrawnTexts/TextWrap, TileMapRenderer.setTexturePosition, main/MainThread, main/Views, main/WindowTree, main/Workers, main/MainLoop.loadingDeadline, main/DisplaySettings, main/WindowPlatform.Parse, inputs/GamepadManager/Gamepad/InputRegistry/InputManager et InputFocus (pile de focus, appuis non transmis), registry/Identifier, algorithms/ (graphes, Dijkstra, Wave Function Collapse, terrain), physics/collision, physics/tweenings et utils/Timer (durée de la frame fixée par GameTimeControl), utils/math (maths, couleurs, géométrie), utils/json, resources/map (cartes, tilesets, positions) et resources/animation (fichiers et images ; pas le lecteur Animation), graphics/GUI/GUI/GUIList/TextFieldModel/ListSelection (champ de texte, sélection de ScrollList), mightylibdemo/scenes/SceneChoices (liste du menu), utils/enginecommand/Commands/CommandLine/CommandScript (complétion, sources, propriétaires, identifiants, niveaux, fenêtre de l'appelant), utils/enginecommand/syntax (analyse, types, options, niveaux, conditions, complétion, aide et JSON), resources/ResourceArguments (sélection de ressources), main/EngineConfig (accès aux commandes), inputs/text/CommandLineEditor/LineEditKeys/ClickCounter, console/ConsoleLog/LogCapture/ConsoleInput/CompletionListing/ConsoleLayout/LogSelection (journal, ancre de défilement, sélections, souris, console copy), inputs/KeyEvent/KeyRepeat, accès bruts de inputs/MouseManager (MouseRawTest), main/ConsoleLogsOptionTest, sounds/SoundLoadInfo, garde des champs publics de toute la bibliothèque (PublicFieldsTest : tout ajout de champ public) ; si oui, relancer mvn -o -q test avant de commiter. python tools/coverage.py (JaCoCo, 20 s) montre ce que les tests exécutent, par paquet. Se demander aussi si elle entre dans ce que les tests peuvent couvrir (logique sans GL : états, références, files, parsing, maths…) ; si oui, ajouter ou compléter le test, et pour un bug corrigé, un test qui le reproduit. Un bug connu non corrigé reste en test @Disabled avec sa raison, pas supprimé.
  • Vérifier en jeu avec un seul appel : python tools/scenario.py "scene Scene2D" wait-loaded "?gl summary" "input ENTER" (compile, lance le jeu, enchaîne les commandes, résume en texte, ferme le jeu ; une fenêtre s'ouvre chez l'utilisateur : le prévenir). Détails : python tools/scenario.py --help et docs/debug-tools.md.
  • Répertoire de travail = racine du dépôt (ressources lues depuis resources/). Point d'entrée : io.github.mightycode.mightylibdemo.main.Main.

Règles pour Claude

  • Philosophie du moteur (docs/decisions.md) : classes de base simples + implémentations concrètes proposées + injection ; l'utilisateur final utilise les classes déjà implémentées, ou hérite + injecte les siennes ; l'usage courant reste facile (« simple » = niveau d'usage de Processing) et la réimplémentation (presque) complète reste possible. Bases sans hypothèse sur un jeu précis, points d'accroche choisis, rien de propre à la démo dans la bibliothèque ; signaler tout système qui impose une implémentation en dur.
  • Penser à long terme, à l'échelle d'un vrai jeu (des milliers de ressources, chargement en continu, nombreuses scènes, mods, projets tiers), pas à celle de la démo : une solution qui suffit à la démo mais ne tiendra pas à cette échelle doit être signalée comme telle, avec la cible durable, et inscrite dans docs/current.md ou docs/later.md. Préférer corriger le modèle qui produit les bugs plutôt qu'empiler des pansements.
  • Économiser les tokens : lire des extraits (Grep, Read avec offset/limit) plutôt que des fichiers entiers ; filtrer les journaux ; réponses courtes ; pas de capture d'écran sauf rendu impossible à vérifier autrement (une seule à la fois, et seulement la zone utile avec screenshot --rect x y largeur hauteur ou --corners x y x2 y2 quand on sait où regarder ; cadrer avec la commande camera) ; si une information manque, ajouter une commande qui la renvoie en texte/JSON.
  • Ne jamais importer io.github.mightycode.mightylibdemo.* depuis mightylib (passer les IDs en paramètre).
  • Tout code GL s'exécute sur le thread principal (y revenir par MainThread.execute) ; les tâches de Workers (dont les workers de Resources) ne font que de l'I/O/CPU. Pas de new Thread pour une tâche courte : utiliser Workers. Toujours créer/détruire les objets GL via GenDeleteResources.
  • Toute ressource GL créée dans une scène est libérée dans unload() (ce que launch a créé) ou release() (ce que init a créé : unload n'est pas appelé si la scène est quittée pendant son chargement) ; vérifier l'état CPU des ressources avec la commande resources ; vérifier les fuites avec l'étape leakcheck <Scène> de scenario.py (voir docs/debug-tools.md).
  • Fins de ligne normalisées par .gitattributes (LF dans le dépôt) : git add normal. Ne pas réécrire de fichier source avec sed (utiliser Edit).
  • Git : dev est la branche de travail, master ne reçoit que des versions finies. Une branche de sujet depuis dev, fusionnée dans dev par /pr-ml (PR GitHub, commit de fusion, pas de squash) ; dev → master seulement quand l'utilisateur demande explicitement une nouvelle version (« commite », « livre », « pousse » ne suffisent pas), et toujours en lui demandant d'abord son numéro : git merge --no-ff dev -m "Merge branch 'dev' for version X.Y.Z" puis tag annoté git tag -a vX.Y.Z -m "Version X.Y.Z" sur cette fusion (pousser avec --follow-tags). Un commit par changement logique, avec la ligne Co-Authored-By demandée par le système. Ne pas modifier/commiter target/ ni .idea/workspace.xml.
  • Fin de chaque objectif : nettoyer les docs dans le même commit, ou dans un commit de docs sur la même branche avant la fusion. current.md/later.md = ce qui reste, jamais l'historique : supprimer la ligne de l'objectif atteint (ou la réduire à son reste), sans « fait ». Décrire le nouvel état dans architecture.md (au présent, sans historique). Relire le fichier après modification : plus aucune trace de ce qui est fini.
  • Un bug existant découvert hors du sujet en cours : le noter dans docs/later.md ou docs/futur-discussion.md (et le signaler), pas le corriger en douce.
  • Avant de commencer un gros point (passage de later.md à current.md), en discuter avec l'utilisateur pour s'assurer que tout est prévu (/planification-ml).
  • Point hebdomadaire : une revue des bonnes pratiques (/revue-pratiques) par semaine. Dernière revue : 2026-11-08. Au début de toute nouvelle discussion, si la dernière revue date de 7 jours ou plus, le rappeler à l'utilisateur (une ligne) avant de commencer. Après chaque revue, mettre à jour cette date.
  • Analyses automatiques, pendant la revue hebdomadaire : python tools/analyse.py (Error Prone + SpotBugs) et python tools/coverage.py (JaCoCo) font partie de la revue ; on analyse leurs résultats puis on choisit les actions à mener (corrections par thème, tests à ajouter), sans date ni rappel à part.
  • Décrire comment vérifier manuellement ce qui n'a pas pu l'être (quelle scène, quoi observer).

Conventions de code

  • Java 11 (pas de record, ni de switch expression). Accolades K&R, 4 espaces, commentaires en anglais, peu de Javadoc.
  • Avant de commiter, relire son diff comme le ferait l'analyseur d'IntelliJ : imports devenus inutiles, diamant, isEmpty(), redondances (docs/bonnes-pratiques.md, point 14).
  • Enums préfixées E, interfaces préfixées I ; utilitaires statiques souvent en PascalCase (GenDeleteResources.GenBuffers, Logger.CheckOpenGLError).
  • Appel GL sensible suivi de Logger.CheckOpenGLError("message") ; dans le code appelé à chaque dessin, l'entourer de if (Logger.isGLErrorCheck()).
  • Logs moteur : System.out/err.println avec préfixe --. Exception inattendue mais gérée : Logger.LogException(message, e) (jamais printStackTrace()) ; échec attendu d'une ressource : ResourceException (une ligne). InterruptedException : remettre le drapeau (Thread.currentThread().interrupt()) et s'arrêter.
  • Toute nouvelle commande déclare son identifiant (espace de noms de son propriétaire), son niveau (USER/CHEAT/DEV), sa description et sa syntaxe déclarée (syntax(racine) : arguments typés, options --nom, descriptions, niveau et condition par branche ; la complétion, l'aide et l'analyse en sortent), et répond par un message lisible pour son niveau (le détail pour le développeur dans les data) ; voir docs/debug-tools.md, section Commandes.
  • Pour tester une fonctionnalité, ajouter une scène de démo plutôt que modifier une existante. Nom sans préfixe Test, dimension en fin de nom (un nom Java ne commence pas par un chiffre) : DisplayModesScene, RopeSimulation2D ; l'inscrire dans MenuScene.