Skip to content

README.md

Latest commit

 

History

History
180 lines (128 loc) · 11.3 KB

README.md

File metadata and controls

180 lines (128 loc) · 11.3 KB
Raw

OpenGOAL Modding Hub

OpenGOAL Modding Branch Jak Trilogy AI Assisted

Contents

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, see 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 reaching the intended objective for each mod. Most commits created with agent assistance carry the (AI-assisted) tag.
  • Documentation for developers: the verified OpenGOAL Lisp wiki lives at docs/modding/lisp_instructions.md — common language patterns and engine architecture in Part 1, per-game specifics in Parts 2-4. It's the only place GOAL code examples live in this repository. Agents consult it 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 behavior 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 has its own README.md at the repository root, including an installation guide, feature list, usage instructions, and a demo video.
  • Contributions & feedback: constructive feedback and contributions are welcome.

Installing a Mod (Players)

This is the generic install flow for any mod published from this repository, using the official OpenGOAL Launcher.

  1. Add the mod source. Open the OpenGOAL Launcher, go to Settings (gear icon, bottom-left), click the "Mods" tab, and paste a catalog URL into the input field. The master catalog gives access to every published mod in one source:

    https://raw.githubusercontent.com/whozghiar/jak-project/master-dev/index.json

    Or add an individual mod branch's own catalog URL instead. Click Add.

    Adding a mod source in the OpenGOAL Launcher settings

  2. Open the mod page. Go to the Mods tab in the left-hand panel and click the mod you just added.

    Selecting the newly added mod from the Mods tab

  3. Choose a version and install. Select a version (the latest is recommended) and click Install.

    Choosing a version and installing the mod

  4. Wait for installation. The Launcher downloads the release archive, extracts it, then runs the mod's own extractor and goalc to decompile and compile the assets. This can take a few minutes depending on the mod.

    Installation progress: download, extraction, decompilation, compilation

  5. Launch the game. Click Play.

    Launching the mod from the OpenGOAL Launcher

  6. Activate the mod in-game. Press L3 + SELECT to open the Mods menu, and toggle the mod on (and adjust its configuration, if it exposes one).

    In-game Mods menu opened with L3 + SELECT

Note

Every mod in this repository ships disabled by default and is toggled on manually from this menu — see docs/modding/guides/mods_menu.md for the underlying mechanism.

Git Architecture & CI/CD Workflows

[open-goal/jak-project] (upstream/master)
         |  (Daily automatic sync at 10:00 UTC: sync-upstream.yaml)
         v
  [whozghiar/jak-project] (origin/master)      <-- Clean upstream mirror (no custom commits)
         |
         |  (Fast-forward / automatic merge)
         v
  [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

10 specialized GitHub Actions workflows automate this pipeline — see the GitHub Actions Workflows Guide for every trigger, exact behavior, and a worked example.

Upstream Sync Status

Sync Upstream

This badge indicates the state of the automated daily synchronization workflow (sync-upstream.yaml) running at 10:00 UTC, which fast-forwards master from upstream open-goal/jak-project and merges that into master-dev:

  • Green: the latest sync (upstream -> master -> master-dev) completed successfully.
  • Red: a conflict or failure occurred during the synchronization.

Mod branches are not synced automatically by this workflow. To catch up a branch with master-dev, run task modding-sync-branch -- --push locally, or (repository owner only, see the workflows guide's Access Control section) trigger the sync-branch-with-master-dev.yml workflow from that branch in the Actions tab. Per-branch mergeability details and ready-to-run resolution commands can be audited locally at any time with task modding-branch-status (add -- --push to auto-merge every clean branch in one pass). Each individual mod branch also carries its own live status badge in its root README.md, driven by branch-sync-check.yaml.

Directory Overview

Directory / File Description
AGENTS.md Unified AI agent directives and modding rules (branching, golden rules, REPL workflow, task reference).
.agents/skills/ Modularized agent skills (GOAL Lisp, engine internals, 3D assets/actors, texture modding, documentation standards).
index.json Consolidated OpenGOAL Launcher mod catalog (all published mods and releases across Jak 1-3).
docs/modding/lisp_instructions.md Verified OpenGOAL Lisp wiki — common patterns and engine model, plus each game's specifics — consult before coding.
docs/modding/guides/github_workflows.md Guide to all 7 GitHub Actions CI/CD workflows, triggers, and branch synchronization.
docs/modding/guides/task_scripts_reference.md Reference for every task command and modding automation script.
docs/modding/guides/mod_distribution_guide.md Multi-platform binary release pipeline and launcher catalog architecture (index.json).
docs/modding/guides/mod_bug_tracking.md Bug reporting automation, release synchronization, and issue triage.
docs/modding/guides/mods_menu.md Unified in-game Mods menu architecture.
docs/saves/ 100%-completion save files for Jak 1, Jak 2, and Jak 3 (vanilla game and mods).
docs/modding/templates/ MOD_README.template.md, mod_menu.template.gc.
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 every task, including Decompiling, Asset Ripping, Tools, and Tests categories, see the full Task 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 the 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

(AI-assisted)