Files
Quadrapassel/docs/VCC_PLUS_WORKFLOW.md

122 lines
6.8 KiB
Markdown

# Build and test with VCC Plus
Use the official [VCC Plus for Mac download](https://vccplus.brianholman.com/downloads/)
and the complete [Quadrapassel source repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel).
The public installed app supplies CMOC, Make, Perl, libraries and disk tools for
this project. Homebrew and a separate emulator/toolchain build are not required
for the installed C-workspace workflow.
## Open the existing project
1. Obtain the complete repository in a writable local folder. Do not download
only `main.c`: the game also needs headers, platform/rules files, text assets,
generator scripts, the Makefile and `vccplus-project.json`.
2. Choose **Develop → C Development…** in VCC Plus and open that existing project.
Keep the supplied settings rather than creating a new Hello Disk project over it.
3. Select **Release**. The game uses its declared Make recipe and `disk` action.
4. Choose **Build Disk**. The configured Build target also produces the disk;
use the action displayed by your installed workspace.
5. Read the complete result, including diagnostics and the memory-bound check.
Use **Show Build Products** to find the build's `Quadrapassel.DSK` and `QUAD.bin`.
VCC Plus builds in a separate work area, so the latest result need not appear
beside the original source files.
Release uses the optimization needed by the bounded memory layout. Preserve
`--data=0E00`, `--limit=7B00` and the 1024-byte stack reserve. The additional link-map
check enforces code/constant addresses `$1400..$7AFF` and static-data addresses
`$0E00..$13FF`.
Do not weaken these guards to make Debug or a larger edit fit.
A fresh anonymous checkout has rebuilt the exact build-05 binary and disk using
the public VCC Plus 3.6.1 bundled Release toolchain. The pristine disk hash is
`d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
See [BUILDS.md](BUILDS.md) for delivery identities and
[MEMORY_LAYOUT.md](MEMORY_LAYOUT.md) for the section contract.
## Launch without losing another program
Save guest programs, source drafts and pending media changes before launching.
**Launch Disk** uses the built disk and the project's declared `DOS` command;
attend to the app's normal floppy-replacement and restart confirmations. Use a
writable test copy and preserve personal score disks.
Mounting a different disk does not replace the program in RAM. For a new build,
start it from a clean Disk BASIC state and actually load it with `DOS`. Verify the
running artifact as well as the mounted filename. The manual loading alternative
is `PCLEAR1`, `LOADM"QUAD.BIN"`, then `EXEC`.
The game supports **CoCo 3 with 128 KB or more**. 128 KB emulation and physical
512 KB CoCo 3 play have been verified. Set up the intended machine and record its
actual RAM/CPU/video configuration when testing a change.
## Connect ChatGPT to this C project
Open **Assistant…** in the C workspace, review the shared files, and select
**Use Project Makefile**. Allow disposable playtests when isolated execution is
wanted. Save a new private connection using the supported export process and
connect it to your assistant. Do not post its token or connection file in source,
issues or chat messages.
Begin with live discovery and a real capabilities request. Confirm this project's
files, revision, approved recipe, declared configuration and disk action. Use only
the tool names and argument schemas returned by the installed connection. The
[MCP setup guide](MCP_SETUP.md) gives a portable checklist; it does not require
a machine-specific connection.
For an owned disposable run:
1. Build the current revision's declared disk action in **Release** and inspect
its result. Bind later observations to its artifact identity.
2. Start a fresh owned playtest of that artifact and poll startup as documented.
A supported retained test disk can be selected only with its matching receipt.
3. Send ordinary guest input, including release intervals. Capture real guest
graphics/audio when those capabilities are advertised. Never change guest
memory/registers to manufacture a score or screen.
4. Test the affected controls, gameplay, saves and return paths. Use advertised
read-only inspection when appropriate; do not invent unavailable debug values.
5. Stop the owned run and retain its writable test-disk receipt. Do not stop
another person's game or delete its media.
Disposable-worker choices depend on the installed app. If a worker advertises
512 KB, that describes the test configuration, not the game's minimum memory.
Do not describe a 512 KB run as an additional 128 KB check. Likewise, actual
joystick states and keyboard aliases are different test evidence. Use supported
native input or a user-controlled physical test when a capability is absent.
Before pointer/keyboard automation, obtain a current idle, unlocked desktop window
unless the user has already granted one for that work. Keep personal machine
settings and media separate from disposable tests.
## Documentation and references
Use **Help → Manual Library…** and discover its search/read tools through the
project connection. For historical CoCo material, **Archive Library…** has its
own read-only sharing connection. Verify each access separately before falling
back to an unrelated source. Public installed CMOC headers/examples are also
valid API references; emulator internals are outside this game's workflow.
Public manual chapters describing the interface and sequence:
- [Build a disk from a folder](https://vccplus.brianholman.com/manuals/programming-in-c/disk-project/)
explains Build, Build Disk, Launch Disk and Show Build Products.
- [Make the first connection](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
explains private connection exports and verifying real access.
- [Build a quiz and give ChatGPT the keyboard](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
demonstrates opening an existing public C project and its Make/disposable loop.
Use standard documented CMOC APIs before new hardware-specific code. The existing
bounded C graphics renderer is a recorded exception; see [AGENTS.md](../AGENTS.md)
and [DECISIONS.md](DECISIONS.md) for its scope. Preserve component licenses.
## Numbered delivery and save data
The recipe's `Quadrapassel.DSK` is a clean staging image. Delivered builds use
`QUADPSLxx.DSK`, with a two-digit number; each changed delivery gets a new filename
and starts with empty high scores/default settings. Verify that neither QPSAVE
file is included before copying to a new numbered filename, compare hashes, and
record the result in [BUILDS.md](BUILDS.md).
Never overwrite an existing numbered or personal disk to deliver a build. Preserve
mounted media, score disks and backups during cleanup. Score migration is a
separate requested action, not an automatic part of a game update.