DeeJanuzandClaude Opus 5.5
b0036cdeae
The README drops the bold headlines on every item and reads as prose. The reference is brought up to date and loses its bold labels. The design doc is reorganized by topic instead of as a dated work log, keeping the technical findings. The setup guide uses subheadings for troubleshooting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.7 KiB
Working on Frametop
Rules for people and coding agents changing this repo. The README covers what Frametop is and how to install it; docs/reference.md covers each component, and docs/design.md records how SteamVR on the Frame behaves and why things are built the way they are. Read its notes on SteamVR before changing how the screens, the pointer, or the input relay talk to SteamVR.
Two ways to run the scripts
Every script works in both modes, and must keep working in both:
- On the Frame (SteamOS, VR variant), commands run locally, in this checkout.
- From a PC over SSH, the repo is synced to
~/dev/frametopon the Frame (scripts/sync.sh), and commands run there.scripts/_env.shworks out which mode applies (FRAME_LOCAL,FRAME_HOST,FRAME_REPO).
scripts/sync.sh # PC -> ~/dev/frametop on the Frame
scripts/frame.sh -C <dir> '<build cmd>' # runs in the "dev" Fedora distrobox
scripts/frame.sh --host '<cmd>' # runs on the SteamOS host
- From a PC, edit only on the PC. The Frame's copy is a mirror that
sync.shoverwrites. - Build inside the
devcontainer. The SteamOS host has a read-only root and no compilers. Container builds link against the container's libraries, so they run in the container (distrobox enter dev -- ...); the SteamVR driver is built to run on the host. - Container packages the build needs go in the list in
setup/dev-container.sh, so the container can be rebuilt. - Build output goes in
build/next to the sources. It's gitignored and never synced.
The headset may be in use
A Steam Frame is someone's personal headset, and they may be wearing it while you work.
- Don't kill or restart
gamescope,steam,vrserver,vrcompositor, the gamescope session, or the Frametop desktop without asking. Each one ends or disrupts whatever is happening in VR. - Don't run host
sudo,steamos-readonly disable,steamos-devmodechanges, pacman installs, or reboots without explicit approval. Only the Bluetooth fixes need hostsudo, and they ask. - Write only inside the repo,
/tmp, and the container unless told otherwise. The installers are the exception: they write the user services, launchers, and the SteamVR driver into the home folder. - Never copy
.netrc, SSH keys, or Steam config off the Frame or into this repo.
Names
User-facing names are "Frametop", "Frametop Display Settings", and "Frametop Input Settings". Programs and files use the ft- / ft_ prefix (ft-screens, ft-pointer, ft-layout, the ft_pointer driver); config, units, and overlay keys use frametop. Program names must stay within 15 characters: Linux truncates process names there, and the scripts find programs with pgrep -x / pkill -x.