Skip to content
 
 

Latest commit

 

History

3,288 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OpenGOAL Modding Hub

OpenGOAL Modding Branch Jak Trilogy AI Assisted

🇬🇧 English Version  •  🇫🇷 Version Française

📑 Summary / Sommaire


🇬🇧 English Version

🎯 Purpose and Approach

This project is an unofficial fork of OpenGOAL, with no direct affiliation with the original OpenGOAL team or Naughty Dog. For the original technical documentation and build instructions of the native port, please refer to the original OpenGOAL README.

Objectives

The goal of this repository is to explore the use of AI to create mods for the Jak trilogy (Jak and Daxter: The Precursor Legacy, Jak II, Jak 3).

Code Reliability and Approach

  • Modifications to compiler & decompiler: Some liberties were taken with the GOAL compiler (goalc), the C++ runtime (game), and the extraction tools (decompiler) to change default behaviors and facilitate AI-assisted modding.
  • Code reliability: The code is not guaranteed to be 100% reliable. The focus is to reach the intended objective for each mod. Most commits created with agent assistance include the (AI-assisted) tag.
  • Documentation for developers: Two curated bilingual references live under docs/modding/jak[x]_lisp_instructions.md (verified OpenGOAL Lisp per game) and engine_generic_concepts.md (shared engine architecture). Agents consult them before coding and never hallucinate an instruction. Mod-specific notes live in each mod branch's root README.md.
  • Two golden rules: (1) native non-regression — a mod never changes default behaviour unless its spec requires it; changes ship OFF by default; (2) In-game Mods toggle — every mod is switchable at runtime from the in-game Mods menu (L3 + SELECT), which works in a normal launcher boot.
  • Dedicated mod README: Each mod branch features its own README.md at the root of the repository, including an installation guide, feature list, usage instructions, and a demo video.
  • Contributions & feedback: Constructive feedback and contributions are welcome.

🌿 Git Architecture & CI/CD Workflows

[open-goal/jak-project] (upstream/master)
         │  (Daily automatic sync at 10:00 UTC: sync-upstream.yaml)
         ▼
  [whozghiar/jak-project] (origin/master)      <── Clean upstream mirror (no custom commits)
         │
         │  (Fast-forward / automatic merge)
         ▼
  [whozghiar/jak-project] (origin/master-dev)  <── Modding base branch (tools, docs, stable base)
         │
         ├── New mod branch: jak[N]/[type]/[name]
         │      │
         │      ├── Root README.md automatically initialized for the mod
         │      ├── Mod source code (goal_src/) + Modding Changes Log in the root README
         │      └── Automated branch mergeability and conflict detection in CI / CLI

GitHub Actions Workflows Pipeline

Our repository relies on 6 specialized CI/CD workflows. For complete architectural documentation and detailed triggers, see the GitHub Actions Workflows Guide:

  1. sync-upstream.yaml (Daily Cron at 10:00 UTC / Dispatch): Fast-forwards master from official OpenGOAL, updates master-dev, auto-merges clean mod branches via scripts/modding/sync_branches_with_master.py, and reports mergeability status in GitHub Actions summary.
  2. branch-sync-check.yaml (On push to jak[1-3]/** / Dispatch): Lightweight ancestry check verifying that a mod branch is strictly up-to-date with master-dev. Powers each mod branch's live status badge in its README.md.
  3. release.yml (Manual workflow_dispatch): Builds fully static Windows and Linux binaries from clean source, packages assets, publishes GitHub Releases, computes SHA256 hashes, and updates the index.json catalog for the OpenGOAL Launcher (see Mod Distribution Guide).
  4. sync-global-catalog.yml (On Release / Workflow Call / Dispatch): Consolidates all published mod releases into the unified root index.json catalog for the OpenGOAL Launcher.
  5. mod-bug-report-sync.yml (On Release): Syncs released mods to the GitHub issue bug report dropdown form.
  6. mod-bug-triage.yml (On Issue open/edit): Parses player bug reports and auto-applies game and mod labels (see Mod Bug Tracking Guide).

Note

Conflict-Free Documentation Strategy: The reference docs (docs/modding/jak[x]_lisp_instructions.md, engine_generic_concepts.md) have a single source of truth: master-dev. They are updated directly via task modding-land-doc (append-only), then pulled into mod branches with task modding-sync-docs. This design guarantees that parallel mod branches never conflict on shared documentation.


📊 Mod Branch Synchronization

Sync Upstream

This badge indicates the state of the automated daily synchronization workflow (sync-upstream.yaml) running at 10:00 UTC:

  • Green: The latest sync (upstream → mastermaster-dev → mod branches) completed successfully with all clean branches merged.
  • Red: A conflict or failure occurred during the synchronization pipeline.

Per-branch mergeability details and ready-to-run resolution commands can be audited locally at any time:

  • 📋 Audit Command: task modding-branch-status (displays status and conflict commands in terminal or CI).

Each individual mod branch also carries its own live status badge in its root README.md driven by branch-sync-check.yaml. For full operational details, refer to the GitHub Actions Workflows Guide.


📂 Directory Overview

Directory / File Description
AGENTS.md Unified AI agent directives and modding rules (branching, golden rules, REPL workflow, task reference).
.agents/skills/ Modularized developer and agent skills (GOAL Lisp, engine internals, 3D assets/actors, texture modding).
index.json Consolidated OpenGOAL Launcher mod catalog (all published mods and releases across Jak 1-3).
docs/modding/ Modding documentation hub (verified Lisp references, engine primer, engineering workflows, tools).
docs/modding/tools/github_workflows.md Comprehensive guide to all 6 GitHub Actions CI/CD workflows, triggers, and branch synchronization.
docs/modding/tools/task_scripts_reference.md Pedagogical reference for all task commands and modding automation scripts.
docs/modding/tools/mod_distribution_guide.md Multi-platform binary release pipeline and launcher catalog architecture (index.json).
docs/modding/tools/mod_bug_tracking.md Bug reporting automation, release synchronization, and issue triage.
docs/modding/tools/mods_menu.md Unified in-game Mods menu architecture (mods-menu-register, L3 + SELECT).
docs/modding/how_to_install_mod.md Step-by-step player guide to installing mods via the official OpenGOAL Launcher.
docs/saves/ 100% completion save files for Jak 1, Jak 2, and Jak 3 (Vanilla game and Mods).
docs/modding/jak1_lisp_instructions.md · jak2 · jak3 Verified OpenGOAL Lisp reference per game — consult before coding.
docs/modding/engine_generic_concepts.md Shared non-Lisp engine primer (memory, heaps, DGOs, level streaming, process life cycle).
docs/modding/templates/ MOD_README.template.md, mod_menu.template.gc.
docs/modding/branch_audit.md Generated per-branch compliance report (task modding-audit).
scripts/modding/ Python automation (branch creation, branch/doc sync, doc landing, branch audit, global catalog sync).
goal_src/ Decompiled and modified GOAL source code by game (jak1/, jak2/, jak3/).
goalc/ OpenGOAL compiler with modding adjustments.
game/ C++ runtime simulating the Emotion Engine memory on PC.
decompiler/ Asset extraction and decompiler tools.
custom_assets/ Custom texture replacements and models.

🛠️ Task Command Reference

Automation and builds are driven by Taskfile. Pass script arguments after --. For an in-depth pedagogical explanation of when and why to use each task, see the Task Commands & Modding Scripts Reference.

Active Target Game Selection

Command Purpose
task set-game-jak1 · -jak2 · -jak3 Persist active target game configuration (jak1, jak2, or jak3)

Build & CMake (3-Layer Rule)

Command Purpose
task gen-cmake-release Configure CMake build system (Ninja + Clang); auto-wires sccache if installed
task build-release Build all ~20 binaries (first setup / full regression check)
task build-release-game Build only gk + goalc — fast iteration for engine runtime & compiler C++
task build-release-decomp Build only the decompiler — use after changing decompiler/, then re-extract
task build-debug / -debug-game / -debug-decomp Debug build equivalents with full symbols
task clean-cmake Remove build artifacts and CMake cache

Asset Extraction & Decompilation

Command Purpose
task extract Extract retail assets and run the decompiler (run after decompiler config edits)
task decomp / decomp-file FILE=… Decompile all objects or a single specific GOAL object
task rip-textures / rip-levels / rip-collision / rip-audio Rip specific asset categories

Interactive REPL & Game Execution

Command Purpose
task repl(mi) Start compiler REPL; (mi) hot-reloads GOAL code directly into running RAM (no C++ build needed)
task boot-game Boot game executable in debug mode without attaching REPL
task boot-game-retail Boot game in retail mode (-boot -fakeiso) to test Mods menu (L3 + SELECT)
task run-game Launch runtime process driven and monitored via REPL connection
task format / format-gsrc FILE=… Format all C++ and GOAL source code or a single .gc file

Modding Workflow Scripts

Command Purpose
task modding-new-branch -- jak2/features/x Create a new mod branch from master-dev with template README.md
task modding-sync-branch Safely merge master-dev into your current mod branch (-- --rebase / -- --push)
task modding-sync-docs Pull latest docs/modding, AGENTS.md, and CLAUDE.md from master-dev
task modding-land-doc -- --file docs/modding/jak2_lisp_instructions.md --message "…" --push Land verified Lisp discoveries on master-dev conflict-free, then re-sync
task modding-sync-catalog Refresh and regenerate the root index.json catalog from published GitHub releases
task modding-branch-status Audit and auto-merge mod branches against master-dev
task modding-audit Regenerate repo-wide compliance audit report (docs/modding/branch_audit.md)

Automated Tests

Command Purpose
task offline-tests / offline-tests-fast Run decompiler regression tests against retail binaries
task unit-tests / tests-filtered FILTER=… Run goalc compiler unit test suite

🇫🇷 Version Française

🎯 Démarche & Objectif du Projet

Ce dépôt est un fork non officiel du projet OpenGOAL, sans affiliation directe avec l'équipe originelle d'OpenGOAL ou Naughty Dog. Pour la documentation technique et les instructions de compilation du port de base, consultez le README originel d'OpenGOAL.

Objectifs

L'objectif de ce projet est d'utiliser l'IA pour créer des mods pour la trilogie Jak (Jak and Daxter: The Precursor Legacy, Jak II, Jak 3).

Fiabilité du code et démarche

  • Modifications du compilateur et décompilateur : Certaines libertés ont été prises au niveau du compilateur GOAL (goalc), du runtime C++ (game) et des outils d'extraction (decompiler) pour modifier des comportements natifs du projet original et faciliter le modding avec l'IA.
  • Fiabilité du code : Le code produit avec l'assistance d'agents IA n'est pas garanti fiable à 100%. L'accent est mis sur l'atteinte de l'objectif fixé pour chaque mod. La plupart des commits correspondants portent la mention (AI-assisted).
  • Documentation pour les développeurs : Deux références bilingues curatées sous docs/modding/jak[x]_lisp_instructions.md (Lisp OpenGOAL vérifié par jeu) et engine_generic_concepts.md (architecture moteur partagée). Les agents les consultent avant de coder et n'hallucinent jamais d'instruction. Les notes propres à un mod vivent dans le README.md racine de sa branche.
  • Deux règles d'or : (1) non-régression native — un mod ne change jamais le comportement par défaut sauf si son cahier des charges l'exige ; les changements sont livrés DÉSACTIVÉS par défaut ; (2) bascule Mods en jeu — tout mod est activable/désactivable à la volée depuis le menu Mods en jeu (L3 + SELECT), qui fonctionne dans un boot normal du launcher.
  • README dédié par mod : Chaque branche de mod dispose à sa racine d'un fichier README.md décrivant : le guide d'installation, les fonctionnalités du mod, son utilisation et une vidéo démonstrative.
  • Contributions et retours : Toute contribution ou suggestion est accueillie avec grand plaisir, tant qu'elle reste constructive et bienveillante.

🌿 Architecture Git & Workflows CI/CD

[open-goal/jak-project] (upstream/master)
         │  (Synchronisation quotidienne automatique à 10:00 UTC : sync-upstream.yaml)
         ▼
  [whozghiar/jak-project] (origin/master)      <── Miroir amont propre (aucun commit custom)
         │
         │  (Fast-forward / fusion automatique)
         ▼
  [whozghiar/jak-project] (origin/master-dev)  <── Branche de base modding (outils, docs, base stable)
         │
         ├── Nouvelle branche de mod : jak[N]/[type]/[nom]
         │      │
         │      ├── README.md racine initialisé automatiquement pour le mod
         │      ├── Code source du mod (goal_src/) + Journal des modifications dans le README
         │      └── Détection et fusion automatique des branches de mods en CI / CLI

Pipeline des Workflows GitHub Actions

Notre dépôt repose sur 6 workflows CI/CD spécialisés. Pour une documentation architecturale complète et le détail des déclencheurs, consultez le Guide des Workflows GitHub Actions :

  1. sync-upstream.yaml (Cron quotidien à 10:00 UTC / Dispatch) : Rapatrie les nouveautés d'OpenGOAL amont sur master, met à jour master-dev, fusionne automatiquement les branches de mods prêtes via scripts/modding/sync_branches_with_master.py, et publie le rapport de synthèse dans GitHub Actions.
  2. branch-sync-check.yaml (Au push sur jak[1-3]/** / Dispatch) : Vérification ultra-rapide d'ascendance garantissant qu'une branche de mod est à jour avec master-dev. Alimente le badge d'état GitHub Actions dans le README.md de chaque mod.
  3. release.yml (Déclenchement manuel workflow_dispatch) : Compile des binaires Windows et Linux entièrement statiques depuis les sources propres, empaquette les assets, publie les releases GitHub, calcule les empreintes SHA256 et met à jour le catalogue index.json du Launcher OpenGOAL (voir le Guide de Distribution des Mods).
  4. sync-global-catalog.yml (À chaque Release / Workflow Call / Dispatch) : Consolide l'ensemble des releases de mods publiées dans le catalogue unifié index.json à la racine pour le Launcher OpenGOAL.
  5. mod-bug-report-sync.yml (À chaque Release) : Synchronise la liste des mods publiés dans le formulaire de rapport de bug GitHub.
  6. mod-bug-triage.yml (À l'ouverture/édition d'un ticket) : Analyse les rapports de bugs des joueurs et applique automatiquement les labels de jeu et de mod (voir le Guide de Suivi des Bugs de Mods).

Note

Stratégie de Documentation Sans Conflit : Les documents de référence (docs/modding/jak[x]_lisp_instructions.md, engine_generic_concepts.md) possèdent une source de vérité unique : master-dev. Ils sont mis à jour directement via task modding-land-doc (en ajout seul), puis rapatriés dans les branches de mods avec task modding-sync-docs. Cette conception évite tout conflit de documentation entre branches développées en parallèle.


📊 Synchronisation des Branches de Mods

Sync Upstream

Ce badge indique l'état d'exécution du workflow de synchronisation quotidienne automatique (sync-upstream.yaml) exécuté chaque jour à 10:00 UTC :

  • Vert : La dernière synchronisation (amont → mastermaster-dev → branches de mods) s'est déroulée avec succès et toutes les branches sans conflit ont été fusionnées automatiquement.
  • Rouge : Un conflit ou un incident est survenu pendant le pipeline de synchronisation.

Le détail branche par branche avec les commandes prêtes à l'emploi pour résoudre les conflits peut être audité à tout moment :

  • 📋 Commande d'audit : task modding-branch-status (affiche le bilan et les commandes de résolution en console ou en CI).

Chaque branche de mod dispose également de son propre badge d'état en direct dans son README.md racine, alimenté par branch-sync-check.yaml. Pour tous les détails d'architecture, consultez le Guide des Workflows GitHub Actions.


📂 Vue d'ensemble des Répertoires

Dossier / Fichier Description
AGENTS.md Directives unifiées pour agents IA et règles de modding (stratégie de branches, règles d'or, workflow REPL, référence des tâches).
.agents/skills/ Compétences modulaires développeurs et agents (GOAL Lisp, moteur interne, assets/acteurs 3D, modding de textures).
index.json Catalogue consolidé pour le Launcher OpenGOAL (tous les mods et releases publiés pour Jak 1-3).
docs/modding/ Hub de documentation du modding (références Lisp vérifiées, guide d'initiation au moteur, workflows d'ingénierie, outils).
docs/modding/tools/github_workflows.md Guide exhaustif des 6 workflows CI/CD GitHub Actions, déclencheurs et synchronisation des branches.
docs/modding/tools/task_scripts_reference.md Référence pédagogique de toutes les commandes task et des scripts Python d'automatisation.
docs/modding/tools/mod_distribution_guide.md Pipeline de release multiplateforme et architecture du catalogue Launcher (index.json).
docs/modding/tools/mod_bug_tracking.md Automatisation des rapports de bugs, synchronisation des releases et triage automatique des tickets.
docs/modding/tools/mods_menu.md Architecture unifiée du menu Mods en jeu (mods-menu-register, L3 + SELECT).
docs/modding/how_to_install_mod.md Guide pas à pas pour les joueurs expliquant comment installer un mod via le Launcher OpenGOAL.
docs/saves/ Sauvegardes terminées à 100% pour Jak 1, Jak 2 et Jak 3 (Jeu original et Mods).
docs/modding/jak1_lisp_instructions.md · jak2 · jak3 Référence Lisp OpenGOAL vérifiée par jeu — à consulter impérativement avant de coder.
docs/modding/engine_generic_concepts.md Guide d'initiation au moteur partagé hors-Lisp (mémoire, heaps, DGOs, streaming de niveaux, cycle de vie des processus).
docs/modding/templates/ Modèles de documentation et de code (MOD_README.template.md, mod_menu.template.gc).
docs/modding/branch_audit.md Rapport de conformité généré par branche (task modding-audit).
scripts/modding/ Automatisation Python (création de branche, synchronisation branche/doc, atterrissage de doc, audit, catalogue global).
goal_src/ Code source GOAL décompilé et modifié par jeu (jak1/, jak2/, jak3/).
goalc/ Compilateur OpenGOAL avec ajustements pour le modding.
game/ Runtime C++ simulant la mémoire de l'Emotion Engine sur PC.
decompiler/ Outils d'extraction d'assets et de décompilation.
custom_assets/ Remplacements de textures et modèles 3D personnalisés.

🛠️ Référence des Commandes Task

L'automatisation et les compilations s'appuient sur Taskfile. Passez les arguments de scripts après --. Pour un guide pédagogique complet détaillant quand et pourquoi employer chaque commande, consultez la Référence des Commandes Task & Scripts de Modding.

Sélection du Jeu Actif

Commande Rôle
task set-game-jak1 · -jak2 · -jak3 Définit et mémorise le jeu actif ciblé (jak1, jak2 ou jak3)

Compilation & CMake (Règle des 3 couches)

Commande Rôle
task gen-cmake-release Configure CMake (Ninja + Clang) ; active automatiquement sccache s'il est présent
task build-release Compile l'ensemble des ~20 binaires (première installation / audit complet)
task build-release-game Compile uniquement gk + goalc — boucle rapide pour le C++ moteur/compilateur
task build-release-decomp Compile uniquement le décompilateur — après modifs dans decompiler/
task build-debug / -debug-game / -debug-decomp Équivalents en mode debug avec symboles complets
task clean-cmake Nettoie les artefacts de build et le cache CMake

Extraction d'Assets & Décompilation

Commande Rôle
task extract Extrait les assets originaux et exécute le décompilateur
task decomp / decomp-file FILE=… Décompile tous les fichiers ou un fichier GOAL précis
task rip-textures / rip-levels / rip-collision / rip-audio Extrait une catégorie d'assets spécifique

REPL Interactif & Exécution du Jeu

Commande Rôle
task repl(mi) Ouvre le REPL goalc ; (mi) injecte le code GOAL en direct en mémoire (aucun build C++ requis)
task boot-game Démarre le jeu en mode debug sans REPL
task boot-game-retail Démarre le jeu en mode retail (-boot -fakeiso) pour tester le menu Mods (L3 + SELECT)
task run-game Lance le runtime, piloté et connecté au REPL
task format / format-gsrc FILE=… Formate le code C++ et GOAL ou un fichier .gc spécifique

Scripts du Workflow de Modding

Commande Rôle
task modding-new-branch -- jak2/features/x Crée une nouvelle branche de mod depuis master-dev avec le template README.md
task modding-sync-branch Fusionne de manière sécurisée master-dev dans votre branche courante
task modding-sync-docs Rapatrie docs/modding, AGENTS.md et CLAUDE.md depuis master-dev
task modding-land-doc -- --file docs/modding/jak2_lisp_instructions.md --message "…" --push Intègre des découvertes Lisp sur master-dev sans conflit, puis resynchronise
task modding-sync-catalog Actualise et régénère le catalogue index.json racine à partir des releases GitHub publiées
task modding-branch-status Audite et fusionne automatiquement les branches de mods avec master-dev
task modding-audit Régénère le rapport d'audit de conformité (docs/modding/branch_audit.md)

Tests Automatisés

Commande Rôle
task offline-tests / offline-tests-fast Exécute les tests de non-régression du décompilateur
task unit-tests / tests-filtered FILTER=… Exécute la suite de tests unitaires du compilateur goalc

(AI-assisted)

About

Reviving the language that brought us the Jak & Daxter Series

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages