From e81974b932c7ca1819843b7bb3dcd42e2993e98e Mon Sep 17 00:00:00 2001 From: tfrere Date: Fri, 4 Sep 2026 15:27:52 +0200 Subject: [PATCH] docs: document git-lfs requirement for local clones A plain clone without LFS serves text pointer files instead of the GLB / ONNX binaries and boots into a SyntaxError (hub discussion #6). Also update the ball paragraph: the ball now syncs over the ghost channel. Co-authored-by: Cursor --- README.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7e252ca..ba82153 100644 --- a/README.md +++ b/README.md @@ -58,9 +58,10 @@ hints fade out; play the ball by driving into it. error...) freeze the console on a `SYSTEM HALTED` screen with the error detail - handy for debugging. -The ball is local-only: it lives in your tab's physics and is not shared -with the multiplayer ghosts. A square arena (3 x 3 m) fences the play -area so neither the ball nor the duck can wander off. +The ball's physics are local to your tab, but its pose is broadcast with +your duck's, so other visitors see a translucent copy of your ball next +to your ghost (and you see theirs). A square arena (3 x 3 m) fences the +play area so neither the ball nor the duck can wander off. ### Gamepad @@ -122,6 +123,18 @@ UI intents in). ## Development +Large binary assets (robot meshes, GLB models, ONNX policies) are stored +with [Git LFS](https://git-lfs.com/). Clone with LFS installed, or pull +the real files after a plain clone - otherwise the app boots against +text pointer files and fails with errors like +`SyntaxError: Unexpected token 'v', "version ht"... is not valid JSON` +(that string is the start of an LFS pointer, not your model): + +```bash +git lfs install # once per machine +git lfs pull # fetch the actual binaries in an existing clone +``` + ```bash cd app npm install