---
description: Treat FrameworkV3 as read-only unless explicitly asked to change the engine; then edit generically, build, and open a GitLab MR.
alwaysApply: true
---

# FrameworkV3 is read-only by default

`client/frameworkv3/` is the **generic client-side engine** (FrameworkV3), not game-specific code. Treat all Framework source and its built bundle as **read-only**.

## Do not edit Framework unless asked

- Do **not** modify files under `client/frameworkv3/` to fix or feature this game.
- Prefer solving game needs in `client/src/`, `shared/`, or `server/` by using Framework APIs as they exist.
- Reading Framework source for understanding APIs is fine; writing is not.

## When the user explicitly asks to change Framework

Only then edit Framework, and keep changes **engine-generic** (reusable for any project that uses FrameworkV3 — no MMO/tile-game specifics, no repo-local hacks).

1. Edit source under `client/frameworkv3/framework/` (not hand-edit the concatenated bundle as the source of truth).
2. Build locally from `client/frameworkv3/`: `./glbuild.sh` (or `framework/build.sh`).
3. In the Framework repo (`client/frameworkv3`, remote `gitlab.com/Timfa/frameworkv3`), create a branch, commit, push, and open a **GitLab merge request** that states:
   - **what** changed
   - **why** (engine capability / bugfix — not “so the MMO can …” as the primary rationale)
4. Do not push to `master` directly; use an MR.

```text
# ❌ BAD — game workaround inside the engine
client/frameworkv3/framework/...  // hardcode tile size / night shade for this MMO

# ✅ GOOD — game uses the engine; engine stays generic
client/src/render/worldView.js    // call existing Scene / Shader / RenderLayer APIs
```
