pleb
85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for coding agents working in this repo.
|
|
|
|
## Project Shape
|
|
|
|
- This repo manages Beat Saber plugins for BSManager instances.
|
|
- Default instance roots are:
|
|
- `~/Windows/Users/pleb/BSManager/BSInstances`
|
|
- `~/.local/share/BSManager/BSInstances`
|
|
- A local BSManager source checkout may be available at
|
|
`~/src/Zagrios/bs-manager`. Use it as a read-only reference when
|
|
investigating launch behavior, inherited Steam arguments, instance layout, or
|
|
Proton environment details unless the user explicitly asks for BSManager code
|
|
changes.
|
|
- Keep plugin source checkouts under `~/src/<owner>/<repo>` when a
|
|
locked or registry plugin has a GitHub source repo. Prefer checking out the
|
|
upstream author/repo first, with `origin` pointing at upstream. If the user has
|
|
an existing personal fork checkout, preserve it as a remote named `github`
|
|
and set/add `origin` to the upstream repo instead of replacing local work.
|
|
- Prefer repo-local state for planned installs unless the task explicitly
|
|
targets the user's live default state. Use `--state-dir .state` for the local
|
|
Linux install and `--state-dir .state-windows` for the mounted Windows install
|
|
when both roots contain the same instance name.
|
|
|
|
## Workflow Rules
|
|
|
|
- Run commands from the repo root with `PYTHONPATH=src`.
|
|
- A repo-local Python virtualenv is normally available at `.venv`; prefer
|
|
`.venv/bin/python` for helper commands and tests when it exists.
|
|
- For human-style inspection, prefer the menu with repo-local state:
|
|
`PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state menu`.
|
|
- When targeting the local Linux BSManager install, pass
|
|
`--instances-root ~/.local/share/BSManager/BSInstances` and normally
|
|
`--state-dir .state`.
|
|
- When targeting the mounted Windows BSManager install, pass
|
|
`--instances-root ~/Windows/Users/pleb/BSManager/BSInstances` and
|
|
normally `--state-dir .state-windows`.
|
|
- Use the helper commands instead of manually copying plugin files into an
|
|
instance.
|
|
- When adding, updating, building, or investigating a GitHub-hosted plugin,
|
|
check for `~/src/<owner>/<repo>` and clone the upstream repo there if
|
|
it is missing. Do not substitute forks or similar repos without explicit user
|
|
direction.
|
|
- Treat BSIPA as a bootstrap phase:
|
|
- `bootstrap` installs the locked BSIPA archive and records generated files.
|
|
- ordinary plugin plans should depend on healthy bootstrap state.
|
|
- Be careful with duplicate instance names across Windows and local roots. Use
|
|
the menu or pass `--instances-root` explicitly when targeting one install, and
|
|
keep install/bootstrap state separate per target root.
|
|
- After completing repo changes, suggest a concise commit message in the final
|
|
response unless the user already asked you to commit.
|
|
|
|
## Validation
|
|
|
|
- Run `PYTHONPATH=src .venv/bin/python -m unittest discover -s tests` after
|
|
code changes when `.venv` exists; otherwise use `python`.
|
|
- Run `PYTHONPATH=src .venv/bin/python -m compileall -q src tests` for
|
|
syntax/import checks when `.venv` exists; otherwise use `python`.
|
|
- For live game validation, follow `docs/SMOKETEST.md` and tear down Beat Saber
|
|
processes afterward.
|
|
|
|
## Pull Requests
|
|
|
|
- When the user asks for a PR against an upstream plugin, compose and submit a
|
|
polite pull request using the user's existing `gh` session.
|
|
- Keep upstream PRs small, focused, and easy for the maintainer to verify. Favor
|
|
narrow compatibility fixes, clear commit messages, and minimal formatting or
|
|
project-file churn.
|
|
- Work from the upstream checkout under `~/src/<owner>/<repo>` when available.
|
|
If the upstream remote is not writable, create or reuse the user's fork with
|
|
`gh repo fork`, push a topic branch there, and open the PR against upstream.
|
|
- Include concise verification notes in the PR body, especially the exact build
|
|
or smoke-test command and any generated artifact name. Mention local-only
|
|
build configuration separately if it was needed, and do not commit machine
|
|
paths or helper state unless the user explicitly asks for it.
|
|
|
|
## Launch Notes
|
|
|
|
- BSManager may inherit Beat Saber launch arguments configured in Steam.
|
|
- Do not assume a black screen is a plugin failure until checking
|
|
`Logs/_latest.log`, Unity `Player.log`, and the live process command line.
|
|
- Duplicate launch args such as `--no-yeet fpfc --no-yeet fpfc` can trigger a
|
|
fatal command-line parse error after BSIPA/plugin loading succeeds.
|