Taskfile.yml

version: 3

includes:
  build: ./scripts/tasks/Taskfile_{{OS}}.yml

dotenv:
  - ./scripts/tasks/.env
  - ./scripts/tasks/.env.default

vars:
  # Compiler cache: if `sccache` is on PATH (install it with `scoop install sccache` on Windows,
  # or your package manager elsewhere), bake it in as the compiler launcher at CMake-generate time.
  # This makes rebuilds after a branch switch / partial revert near-instant for unchanged files -
  # the same trick the CI uses (see .github/workflows/windows-build-clang.yaml). No-op if sccache
  # is not installed, so this stays safe on every platform.
  SCCACHE_FLAGS:
    sh: command -v sccache >/dev/null 2>&1 && echo "-DCMAKE_C_COMPILER_LAUNCHER=sccache -DCMAKE_CXX_COMPILER_LAUNCHER=sccache" || true

tasks:
  # SETTINGS / CONFIGURATION
  settings:
    - "{{.PYTHON}} ./scripts/tasks/update-env.py --info"
  set-game-jak1:
    - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak1"
  set-game-jak2:
    - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak2"
  set-game-jak3:
    - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak3"
  set-game-jakx:
    - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jakx"
  set-decomp-ntscv1:
    desc: "aka black label"
    cmds:
      - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv1"
  set-decomp-ntscv2:
    desc: "aka red label"
    cmds:
      - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv2"
  set-decomp-pal:
    desc: "PAL region version"
    cmds:
      - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config pal"
  set-decomp-ntscjp:
    desc: "NTSC-J region version"
    cmds:
      - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscjp"
  set-decomp-ntscko:
    desc: "NTSC-K region version"
    cmds:
      - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscko"
  # GENERAL
  extract:
    desc: "Extracts the game's assets from './iso_data' with the set decompiler config"
    preconditions:
      - sh: test -f {{.DECOMP_BIN_RELEASE_DIR}}/decompiler{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate decompiler executable in '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler'"
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "allowed_objects": []}'''
  boot-game:
    desc: "Boots the game, it will fail if it's not already compiled!"
    preconditions:
      - sh: test -f {{.GK_BIN_RELEASE_DIR}}/gk{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate runtime executable in '{{.GK_BIN_RELEASE_DIR}}/gk'"
    cmds:
      - "{{.GK_BIN_RELEASE_DIR}}/gk -v --game {{.GAME}} -- -boot -fakeiso -debug"
  boot-game-retail:
    desc: "Boots the game without debug mode, it will fail if it's not already compiled!"
    preconditions:
      - sh: test -f {{.GK_BIN_RELEASE_DIR}}/gk{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate runtime executable in '{{.GK_BIN_RELEASE_DIR}}/gk'"
    cmds:
      - "{{.GK_BIN_RELEASE_DIR}}/gk -v --game {{.GAME}} -- -boot -fakeiso"
  run-game:
    desc: "Start the game's runtime, to start the game itself the REPL is required"
    preconditions:
      - sh: test -f {{.GK_BIN_RELEASE_DIR}}/gk{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate runtime executable in '{{.GK_BIN_RELEASE_DIR}}/gk'"
    cmds:
      - "{{.GK_BIN_RELEASE_DIR}}/gk -v --game {{.GAME}} -- -fakeiso -debug"
  # DEVELOPMENT
  clean-cmake:
    desc: "Cleans up any existing cmake artifacts"
    cmds:
      - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path ./build"
      - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path ./out/build"
  gen-cmake:
    desc: "Generate the CMake"
    cmds:
      - "cmake {{.CMAKE_GEN_BUILD_DIR_DEBUG}} --preset={{.CMAKE_PRESET}}"
  gen-cmake-release:
    desc: "Generate the CMake"
    cmds:
      - "cmake {{.CMAKE_GEN_BUILD_DIR_RELEASE}} --preset={{.DEFAULT_CMAKE_RELEASE_PRESET}} {{.SCCACHE_FLAGS}}"
  gen-cmake-debug:
    desc: "Generate the CMake"
    cmds:
      - "cmake {{.CMAKE_GEN_BUILD_DIR_DEBUG}} --preset={{.DEFAULT_CMAKE_DEBUG_PRESET}} {{.SCCACHE_FLAGS}}"
  build:
    desc: "Build the project using the generated CMake"
    cmds:
      # --config is a no-op for single-config generators (Ninja, the project's default via
      # gen-cmake-*) but is required for a multi-config generator (e.g. Visual Studio, if a build
      # dir was configured that way instead) - without it, `cmake --build` silently defaults to a
      # Debug build even under out/build/Release. Cheap to always pass, fixes that trap either way.
      # --parallel with no number lets the generator use every core (was hard-capped at 8).
      - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --config Debug --parallel"
  build-release:
    desc: "Build the project using the generated CMake"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_RELEASE}} --config Release --parallel"
  build-debug:
    desc: "Build the project using the generated CMake"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --config Debug --parallel"
  build-release-game:
    desc: "Build only the game runtime + compiler (gk, goalc) - much faster than build-release for mod iteration, skips lsp/decompiler/tools/tests/third-party binaries"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_RELEASE}} --config Release --target gk --target goalc --parallel"
  build-debug-game:
    desc: "Build only the game runtime + compiler (gk, goalc) in Debug - see build-release-game"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --config Debug --target gk --target goalc --parallel"
  build-release-decomp:
    desc: "Build only the decompiler - use when a mod changes decompiler/ C++ code, then re-run `task extract` / `task decomp` / `task update-gsrc-file`"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_RELEASE}} --config Release --target decompiler --parallel"
  build-debug-decomp:
    desc: "Build only the decompiler in Debug - see build-release-decomp"
    cmds:
      - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --config Debug --target decompiler --parallel"
  repl:
    desc: "Start the REPL"
    preconditions:
      - sh: test -f {{.GOALC_BIN_RELEASE_DIR}}/goalc{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate compiler executable in '{{.GOALC_BIN_RELEASE_DIR}}/goalc'"
    cmds:
      - "{{.GOALC_BIN_RELEASE_DIR}}/goalc --user-auto --game {{.GAME}}"
  format-json:
    desc: "Format code"
    cmds:
      # npm install -g prettier
      - cmd: npx prettier --write ./decompiler/config/jak*/**/*.jsonc
        ignore_error: true
  format:
    desc: "Format code"
    cmds:
      - cmd: "{{.PYTHON}} ./scripts/cpp/format-includes.py"
      - cmd: "{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py --fix"
      - cmd: "{{.PYTHON}} ./third-party/run-clang-format/run-clang-format.py -r common decompiler game goalc test tools lsp -i"
      - task: format-json
  format-gsrc:
    desc: "Run formatter on gsrc file"
    preconditions:
      - sh: test -f {{.FORMATTER_BIN_RELEASE_DIR}}/formatter{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate formatter executable in '{{.FORMATTER_BIN_RELEASE_DIR}}/formatter'"
    cmds:
      - "{{.FORMATTER_BIN_RELEASE_DIR}}/formatter --write --file '{{.FILE}}'"
  # MODDING WORKFLOW
  # Thin wrappers over scripts/modding/*.py so the mod workflow is discoverable via
  # `task --list`. Pass script args after `--`, e.g. `task modding-new-branch -- jak2/features/foo`.
  modding-new-branch:
    desc: "Create a new mod branch from master-dev with an initialised root README (scripts/modding/create_mod_branch.py). Args after --, e.g. -- jak2/features/my-mod"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/create_mod_branch.py {{.CLI_ARGS}}"
  modding-sync-branch:
    desc: "Sync the current mod branch with master-dev via safe git merge (scripts/modding/sync_branch_with_master_dev.py). --rebase / --push accepted after --"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/sync_branch_with_master_dev.py {{.CLI_ARGS}}"
  modding-sync-docs:
    desc: "Pull .agents + docs/modding + AGENTS.md + CLAUDE.md from master-dev into the current branch, pruning files deleted upstream (scripts/modding/sync_docs_from_master.py)"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/sync_docs_from_master.py {{.CLI_ARGS}}"
  modding-land-doc:
    desc: "Land a lisp/engine doc change on master-dev conflict-free, then re-sync your branch (scripts/modding/land_doc_on_master_dev.py). e.g. -- --file docs/modding/lisp_instructions.md --message '...' --push"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/land_doc_on_master_dev.py {{.CLI_ARGS}}"
  modding-branch-status:
    desc: "Test every mod branch's mergeability with master-dev (scripts/modding/sync_branches_with_master.py). Add -- --push to auto-merge clean branches"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/sync_branches_with_master.py {{.CLI_ARGS}}"
  modding-audit:
    desc: "Regenerate docs/modding/branch_audit.md: per-branch compliance with the modding standards (scripts/modding/branch_audit.py)"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/branch_audit.py {{.CLI_ARGS}}"
  modding-sync-bug-report-options:
    desc: "Refresh the mod-bug-report.yml 'Mod Concerned' dropdown from actually-published GitHub Releases (scripts/modding/sync_bug_report_options.py). Add -- --dry-run to preview"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/sync_bug_report_options.py {{.CLI_ARGS}}"
  modding-sync-catalog:
    desc: "Regenerate master-dev root index.json global catalog from published GitHub Releases (scripts/modding/sync_global_catalog.py). Add -- --offline or --dry-run"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/sync_global_catalog.py {{.CLI_ARGS}}"
  modding-package-texture-pack:
    desc: "Register texture pack .zip from docs/modding/current_mod/texture_packs/ (built by Texture Pack Generator GUI) into index.json (scripts/modding/package_texture_pack.py). Add -- --help for options"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/package_texture_pack.py {{.CLI_ARGS}}"
  modding-register-texture-pack:
    desc: "Alias for modding-package-texture-pack: register texture pack .zip from docs/modding/current_mod/texture_packs/ into index.json"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/package_texture_pack.py {{.CLI_ARGS}}"
  modding-texture-gui:
    desc: "Launch the OpenGOAL Texture Pack Generator GUI tool (Tauri v2 desktop app) to preview and package texture packs"
    cmds:
      - "{{.PYTHON}} ./scripts/modding/launch_texture_gui.py {{.CLI_ARGS}}"

  # DECOMPILING
  disasm:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"disassemble_code": true, "dump_function_metadata": true, "levels_extract": false}'''
  decomp-no-override:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}"'
  decomp:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": true, "levels_extract": false}'''
  disasm-file:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"disassemble_code": true, "decompile_code": false, "levels_extract": false, "allowed_objects": ["{{.FILE}}"]}'''
  decomp-file:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": true, "levels_extract": false, "allowed_objects": ["{{.FILE}}"]}'''
  decomp-clean:
    cmds:
      - '{{.PYTHON}} ./scripts/tasks/clean-decomp.py --game "{{.GAME}}"'
  lint-gsrc-file:
    cmds:
      - '{{.PYTHON}} ./scripts/gsrc/lint-gsrc-file.py --game {{.GAME}} --file "{{.FILE}}"'
  update-gsrc:
    cmds:
      - '{{.PYTHON}} ./scripts/gsrc/update-gsrc-via-refs.py --game "{{.GAME}}" --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler" --decompiler_config {{.DECOMP_CONFIG}} --version {{.DECOMP_CONFIG_VERSION}}'
  update-gsrc-glob:
    cmds:
      - '{{.PYTHON}} ./scripts/gsrc/update-gsrc-via-refs.py --game "{{.GAME}}" --file_pattern "{{.GLOB}}" --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler" --decompiler_config {{.DECOMP_CONFIG}} --version {{.DECOMP_CONFIG_VERSION}}'
  update-gsrc-file:
    cmds:
      - task: decomp-file
      - '{{.PYTHON}} ./scripts/gsrc/update-from-decomp.py --game "{{.GAME}}" --file "{{.FILE}}"'
      - task: lint-gsrc-file
  copy-common-naming:
    cmds:
      - '{{.PYTHON}} ./scripts/gsrc/copy-common-naming.py --file "{{.FILE}}" --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler"'
      - task: format-json
  copy-common-naming-from-refs:
    cmds:
      - '{{.PYTHON}} ./scripts/gsrc/copy-common-naming.py --update-names-from-refs --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler"'
      - task: format-json
  # ASSET RIPPING
  rip-textures:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "save_texture_pngs": true}'''
  rip-levels:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "rip_levels": true}'''
  rip-collision:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "extract_collision": true, "rip_collision": true}'''
  rip-audio:
    cmds:
      - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "rip_streamed_audio": true}'''
  # TOOLS
  analyze-ee-memory:
    cmds:
      - '{{.PYTHON}} ./scripts/tasks/extract-zip.py --file "{{.FILE}}" --out ./savestate_out/'
      - "{{.MEMDUMP_BIN_RELEASE_DIR}}/memory_dump_tool ./savestate_out/eeMemory.bin --output-path ./ --game {{.GAME}} > ee-analysis.log"
  watch-pcsx2:
    # {{.PYTHON}} -m pip install -U "watchdog[watchmedo]"
    cmds:
      - watchmedo shell-command --drop --patterns="*.p2s" --recursive --command='task analyze-ee-memory FILE="${watch_src_path}"' "{{.SAVESTATE_DIR}}"
    vars:
      SAVESTATE_DIR: '{{default "." .SAVESTATE_DIR}}'
  type-search:
    desc: Just an example to show it running
    cmds:
      - '{{.TYPESEARCH_BIN_RELEASE_DIR}}/type_searcher --output-path ./search-results.json --game {{.GAME}} --fields ''[{"type":"int16","offset":2},{"type":"int16","offset":4}]'''
  update-treesitter:
    desc: Updates locally built tree-sitter rules
    cmds:
      - cd ../tree-sitter-opengoal && yarn gen
      - '{{.PYTHON}} ./scripts/tasks/cp.py --src "../tree-sitter-opengoal/src/*" --dest "./third-party/tree-sitter/tree-sitter-opengoal"'
      - '{{.PYTHON}} ./scripts/tasks/cp.py --src "../tree-sitter-opengoal/grammar.js" --dest "./third-party/tree-sitter/tree-sitter-opengoal"'
  fix-translations:
    desc: Finds and tries to fix invalid translation Characters
    cmds:
      - "{{.PYTHON}} ./scripts/ci/lint-autoglottonyms.py --fix"
      - "{{.PYTHON}} ./scripts/ci/lint-characters.py --fix"
  lint:
    cmds:
      - "{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py"
  run-gpu-test:
    desc: "Runs the game's built in GPU test"
    preconditions:
      - sh: test -f {{.GK_BIN_RELEASE_DIR}}/gk{{.EXE_FILE_EXTENSION}}
        msg: "Couldn't locate runtime executable in '{{.GK_BIN_RELEASE_DIR}}/gk'"
    cmds:
      - "{{.GK_BIN_RELEASE_DIR}}/gk -v --gpu-test opengl --gpu-test-out-path ./gpu-test.json"
  # TESTS
  unit-tests:
    cmds:
      - "{{.GOALCTEST_BIN_DEBUG_DIR}}/goalc-test{{.EXE_FILE_EXTENSION}} {{.TEST_FILTER}}"
  offline-tests: # ran by jenkins
    cmds:
      - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --fail-on-cmp'
  offline-test-file:
    cmds:
      - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --file {{.FILE}}'
  offline-tests-fast:
    cmds:
      - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --pretty-print --num_threads 8 --dump_current_output --fail-on-cmp'
  # TODO - amalgamate offline-tests and this task, run twice if the previous step fails
  update-ref-tests:
    cmds:
      - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures"
      - cmd: '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --pretty-print --num_threads 8 --dump_current_output --fail-on-cmp'
        ignore_error: true
      - "{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}"
      - task: offline-tests-fast
  update-ref-file:
    cmds:
      - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures"
      - cmd: '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --file {{.FILE}} --game {{.GAME}} --dump_current_output --fail-on-cmp'
        ignore_error: true
      - "{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}"
      - task: offline-test-file
  type-test:
    cmds:
      - cmd: '{{.GOALCTEST_BIN_RELEASE_DIR}}/goalc-test --gtest_brief=0 --gtest_filter="*{{.TYPE_CONSISTENCY_TEST_FILTER}}*" --gtest_break_on_failure'
  tests-filtered:
    cmds:
      - cmd: '{{.GOALCTEST_BIN_RELEASE_DIR}}/goalc-test --gtest_brief=0 --gtest_filter="*{{.FILTER}}*" --gtest_break_on_failure'