# Quest Student Game Common Errors

Use this guide to diagnose common AI-generated student game problems.

## Multiplayer Backend Added

Problem:
- The AI added Express, Socket.IO, Colyseus, or a custom WebSocket backend.

Fix:
- Remove the custom backend from the student project.
- Keep the game as a static browser build.
- Use the Quest Multiplayer SDK.
- Read https://agents.joinquest.com/docs/multiplayer-sdk.md.

## Game Sends Too Much Network Data

Problem:
- The game sends full world snapshots or player data every frame.

Fix:
- Send presence on a timer, about every 125ms to 250ms.
- Do not resend unchanged presence.
- Store only changed world data in shared state.
- Use events for one-off actions.

## Remote Players Do Not Appear

Check:
- The player joined after entering a nickname.
- `onPlayersChange()` is registered after joining.
- The local player is skipped using `session.getPlayerId()`.
- Remote players have `presence.position`.
- The game creates or updates remote player meshes outside the animation loop.

## Game Freezes When Time Runs Out

Common cause:
- Multiple systems are trying to end the game.

Fix:
- Use one `state.mode`.
- Use one transition function.
- Clamp timers once.
- Add a boolean latch such as `hasEnded`.

## Movement Feels Backward

Common cause:
- Three.js forward direction or camera-relative movement math is wrong.

Fix:
- Remember that `+X` is right, `+Y` is up, and `+Z` is toward the camera.
- Object forward is usually local `-Z`.
- Fix vector math instead of remapping keys.
- If A or D is inverted, check the cross product order.

## Objects Float Above Or Sink Into Ground

Fix:
- Characters should have their bottom at `y = 0`.
- Ground tiles should have their top at `y = 0`.
- Do not add random y-offset fixes in many files.
- If a model needs adjustment, wrap it in a parent `Object3D` and offset it once.

## Slow Or Choppy Rendering

Check:
- Geometry and materials are not created inside the animation loop.
- `renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))` is used.
- Materials and geometries are reused.
- Segment counts are reasonable.
- Debug helpers are removed before final delivery.

## Deploy Reports Success With Warnings

Warnings like this are not failures:

```txt
Some chunks are larger than 500 kB after minification
```

Use `QUEST_DEPLOY_RESULT {"status":"success",...}` as the source of truth when it appears.

## Deploy Missing Token Or Command

Fix:
- Ask the student for the exact Quest deploy command.
- Do not invent tokens, project ids, versions, or URLs.
- Do not deploy until the command is provided.