Files
Quadrapassel/docs/VCC_PLUS_WORKFLOW.md

6.8 KiB

Build and test with VCC Plus

Use the official VCC Plus for Mac download and the complete Quadrapassel source repository. 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 for delivery identities and 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 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:

Use standard documented CMOC APIs before new hardware-specific code. The existing bounded C graphics renderer is a recorded exception; see AGENTS.md and 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.

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.