From c09496579f6b79a6585b494b4788d223285e73c8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 1 Apr 2026 18:41:06 +0000 Subject: [PATCH 1/3] Add Cursor Cloud specific instructions to AGENTS.md - Document Love2D v12 nightly installation path and LD_LIBRARY_PATH setup - Document lua-https build-from-source steps for the Cloud VM - Note ALSA audio errors are expected in headless environments - Document backend service requirements (World API + Nakama) - Reference existing linting and testing documentation Co-authored-by: Rodrigo Stramantinoli --- AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5f6f023..0bfccde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -253,3 +253,54 @@ pre-built artifact from its GitHub Actions CI for the target OS. See `DEVELOPMEN `lib/lurker.lua` is called on every `love.update()`. Saving any `.lua` file will automatically reload it in the running game — no restart required during development. + +--- + +## Cursor Cloud specific instructions + +### Environment overview + +Love2D v12 nightly is installed at `/opt/love2d/` with its binary at `/opt/love2d/bin/love` +(symlinked to `/usr/local/bin/love`). The shared libraries live in `/opt/love2d/lib/` and +`LD_LIBRARY_PATH` is configured in `~/.bashrc` to include that path. + +The `lua-https` native module (`https.so`) must exist in the project root (`/workspace/https.so`) +for any API/network calls to work. It is built from source +([love2d/lua-https](https://github.com/love2d/lua-https)) using cmake + g++ against libcurl and +openssl. If it is missing, rebuild it: + +```bash +cd /tmp && git clone --depth 1 https://github.com/love2d/lua-https.git +mkdir -p /tmp/lua-https/build && cd /tmp/lua-https/build +cmake .. -DCMAKE_CXX_COMPILER=g++ -DUSE_CURL_BACKEND=ON -DUSE_OPENSSL_BACKEND=ON +make -j$(nproc) +cp src/https.so /workspace/https.so +``` + +### Running the game + +```bash +export LD_LIBRARY_PATH=/opt/love2d/lib:$LD_LIBRARY_PATH +love . +``` + +ALSA audio errors in the log are expected (no sound device in the VM) and do not affect +gameplay. `conf.lua` sets `t.window.displayindex = 2`; this works in the Cloud VM (which +has a virtual display), but on a single-monitor setup change it to `1`. + +### Backend services + +The game client requires two external services for full end-to-end testing: + +- **World API** (Django REST) at `http://localhost:8000` — auth, users, decks, cards +- **Nakama** server at `localhost:7350` — real-time multiplayer + +Neither service is in this repository. Without them, the game launches to the initial +server-selection screen and responds to UI interaction, but cannot authenticate or enter +a match. The `.env` file (copied from `.env.example`) configures these endpoints. + +### Linting and testing + +- **Lint:** `luacheck .` — see `AGENTS.md` § Linting for details. +- **Tests:** No project-level test suite exists. Manual testing is done by running + `love .` and interacting with the game. From 58921f3d700a68c6bb2deea98f4598343132c573 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 1 Apr 2026 19:53:52 +0000 Subject: [PATCH 2/3] Add backend setup instructions to AGENTS.md Cloud section - Document Docker Compose workflow for backend services (Postgres, API, Nakama, SeaweedFS) - Add first-time SeaweedFS S3 credential and card seeding instructions - Document backend test command - Add Docker-in-VM setup notes (fuse-overlayfs, iptables-legacy) Co-authored-by: Rodrigo Stramantinoli --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0bfccde..bfc91b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -295,12 +295,50 @@ The game client requires two external services for full end-to-end testing: - **World API** (Django REST) at `http://localhost:8000` — auth, users, decks, cards - **Nakama** server at `localhost:7350` — real-time multiplayer -Neither service is in this repository. Without them, the game launches to the initial -server-selection screen and responds to UI interaction, but cannot authenticate or enter -a match. The `.env` file (copied from `.env.example`) configures these endpoints. +The backend is cloned at `/workspace/backend` and runs via Docker Compose. To start all +backend services: + +```bash +cd /workspace/backend +docker compose up -d --build +``` + +This starts: Postgres (5432), API (8000), Nakama (7349-7351), and SeaweedFS (8333). +Migrations and `ensure_nakama_card_fdw` run automatically on API container startup +via `entrypoint.sh`. + +**First-time SeaweedFS setup** (only needed once, after the containers are running): + +```bash +# Create S3 credentials +docker compose exec seaweedfs-master weed shell -master=seaweedfs-master:9333 <<'EOF' +s3.configure -user=wildleague -access_key=wildleague -secret_key=wildleague-secret -buckets=cards -actions=Read,Write,List,Tagging,Admin -apply +EOF + +# Seed card data + mirror images to S3 +docker compose exec api python manage.py seed_default_cards + +# Allow anonymous read access to card images +docker compose exec seaweedfs-master weed shell -master=seaweedfs-master:9333 <<'EOF' +s3.configure -user=anonymous -actions=Read:cards,List:cards -apply +EOF +``` + +**Backend tests:** `docker compose exec api python manage.py test` + +Without the backend, the game launches to the server-selection screen but cannot +authenticate or enter a match. ### Linting and testing -- **Lint:** `luacheck .` — see `AGENTS.md` § Linting for details. -- **Tests:** No project-level test suite exists. Manual testing is done by running - `love .` and interacting with the game. +- **Lint (game):** `luacheck .` — see `AGENTS.md` § Linting for details. +- **Tests (game):** No project-level test suite exists. Manual testing via `love .`. +- **Lint (backend):** No linter configured; follow `.editorconfig`. +- **Tests (backend):** `docker compose exec api python manage.py test` (in `/workspace/backend`). + +### Docker in the Cloud VM + +Docker is installed with `fuse-overlayfs` storage driver and `iptables-legacy` for +compatibility in the nested container environment. Start the daemon with +`sudo dockerd &>/tmp/dockerd.log &` if it's not already running. After starting, +run `sudo chmod 666 /var/run/docker.sock` for non-root access. From da99b3bdcdcff76bfb658d47e3498f0e548029ff Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 2 Apr 2026 13:13:25 +0000 Subject: [PATCH 3/3] Remove insecure chmod 666 on Docker socket from AGENTS.md The ubuntu user is already in the docker group, which is the standard and safer way to grant non-root Docker access. Co-authored-by: Rodrigo Stramantinoli --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bfc91b6..e85e98e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -339,6 +339,6 @@ authenticate or enter a match. ### Docker in the Cloud VM Docker is installed with `fuse-overlayfs` storage driver and `iptables-legacy` for -compatibility in the nested container environment. Start the daemon with -`sudo dockerd &>/tmp/dockerd.log &` if it's not already running. After starting, -run `sudo chmod 666 /var/run/docker.sock` for non-root access. +compatibility in the nested container environment. The `ubuntu` user is in the `docker` +group for non-root access. Start the daemon with `sudo dockerd &>/tmp/dockerd.log &` +if it's not already running.