Installation

Installation

Home · Technical-Overview · Configuration

Requirements

• A current Node.js and npm installation compatible with the project's Vite 7 dependencies. The repository does not declare an engines field with a pinned Node version.
• A modern browser with WebGL support to run the game.
• A Convex account/project for local authentication, persistence, dailies, photos, and leaderboard features.

Get the game source

git clone https://github.com/suryanarayanrenjith/Forest-Survival.git
cd Forest-Survival
npm install

The separate wiki repository can be cloned independently if you are publishing or editing documentation.

Configure Convex

The React entry creates a Convex client from VITE_CONVEX_URL. Provision a development deployment before running the full app:

npx convex dev
npx @convex-dev/auth

convex dev provisions/pushes the development backend and writes the local Convex URL into .env.local. The auth command is a one-time setup for auth keys on that deployment.

Run locally

npm run dev

Vite's normal development URL is typically http://localhost:5173. Use the URL printed by Vite if the port changes.

Verify a production build

npm run lint
npm run build
npm run preview

npm run build runs tsc -b followed by vite build. npm run preview serves the already-built dist output for local checking.

Local multiplayer notes

Multiplayer is PeerJS-based. Create a lobby from one browser/session, then paste the displayed lobby ID into another session. Testing with separate browser profiles or separate devices avoids confusing shared authentication/session state.

Troubleshooting

Symptom	Check
Blank/error game screen	Confirm the browser supports WebGL and hardware acceleration is enabled. The app presents a WebGL-specific warmup error when it detects no usable context.
Convex client/auth failure	Confirm VITE_CONVEX_URL exists in .env.local after npx convex dev, and that the Convex dev process/deployment is available.
Missing saved progress	Sign in; guest and Tutorial sessions intentionally do not persist all progression.
Multiplayer cannot join	Verify the lobby ID, network/WebSocket access for PeerJS, and that the host remains connected.
Slow frame rate	Lower the graphics preset, render scale, draw distance, particle density, and maximum enemies in Settings.

Implementation references: README.md, package.json, src/main.tsx, vite.config.ts, convex/auth.config.ts.