cluaupp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0
+
+- Product name: **Cluaupp** (C++ × Luau)
+- First public release
+- CLI: `init`, `build`, `watch`, `--version`
+- Transpile C++ subset → Luau `--!strict`
+- `local` and `const x = ...`
+- Full Roblox API from the official dump (925 classes, 636 enums)
+- Datatypes: Vector3, Vector2, CFrame, UDim, UDim2, Color3, BrickColor, Rect, Ray, …
+- `Enum::Material::Plastic` → `Enum.Material.Plastic`
+- GitHub Pages site for every class, method, and event
+- Game template + IntelliSense header (`roblox.hpp`, `compile_flags.txt`, clangd)
+- IntelliSense headers are valid C++: `LuaArray` for `GetPlayers`, templated `Connect`, optional dump defaults (`FindFirstChild`), no recursive `Vector3.Unit` field
+- Libraries: full GitHub systems in CluauppLibs (Janitor, Promise, Fusion, Iris, Cmdr, TopbarPlus, Chrono, DataServiceV2, EzVisualz, StateMachine, Spring, Display, Module3D, FormatNumber) plus Cluaupp originals (Net, MathUtils, Twinkle, StickyBillboard, VfxUtil)
+- Wally is optional; `node scripts/vendor-libs.js` re-copies from `vendor/` clones
+- Moonwave docs (C++ types, const, safety, organization)
+- Service architecture: filename tags (`.server` / `.client` / `.legacy.*` / module) plus AST intent scoring (combat, cache, players, …) — not leaderstats-only
+- Type functions ArrayIndexer (`Table`) and Occlude (`Keys`) in CluauppLibs

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cluaupp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# Cluaupp
+
+<p align="center">
+  <img src="site/assets/logo.png" alt="Cluaupp" width="160">
+</p>
+
+**The definitive merge of C++ and modern Luau.**
+
+[Docs](https://kartzrbx.github.io/Cluaupp/) · [Learn](https://kartzrbx.github.io/Cluaupp/learn/) · [API](https://kartzrbx.github.io/Cluaupp/api/classes/)
+
+The cinematic docs site deploys to [Vercel](https://vercel.com) from `site/` (`vercel.json`). Code blocks use **Dark Modern**, **Tokyo Night**, and **Dracula**. Ask Cluaupp (AI Gateway) is the floating chat on the Vercel deploy.
+
+```bash
+cp .env.example .env.local   # set AI_GATEWAY_API_KEY
+npx vercel
+```
+
+[![npm version](https://img.shields.io/npm/v/cluaupp.svg)](https://www.npmjs.com/package/cluaupp)
+[![Node.js](https://img.shields.io/node/v/cluaupp.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Source-to-source transpiler: you write a C++ subset, Cluaupp emits modern [Luau](https://luau.org/getting-started) (`--!strict`, `local`, `const`). C++ structure, Luau quality, one language.
+
+No WASM. No Emscripten. No `lua_call`. Roblox APIs come out as they do in Studio: `game:GetService("Players")`, `player:FindFirstChild("leaderstats")`, `players:GetPlayers()`.
+
+```cpp
+auto* players = GetService<Players>();
+for (auto* player : players->GetPlayers()) {
+	CreateLeaderstats(player);
+}
+players->PlayerAdded.Connect(CreateLeaderstats);
+
+auto* part = new Part(workspace);
+part->Size = Vector3(8, 1, 8);
+part->CFrame = CFrame::lookAt(Vector3(0, 10, 0), Vector3(0, 10, -10));
+frame->Size = UDim2::fromScale(1, 1);
+```
+
+becomes
+
+```luau
+--!strict
+local players: Players = game:GetService("Players")
+for _, player in players:GetPlayers() do
+	CreateLeaderstats(player)
+end
+players.PlayerAdded:Connect(CreateLeaderstats)
+```
+
+## Install
+
+Node.js 18+ and [Rojo](https://rojo.space/) for Studio sync.
+
+```bash
+npm install -g cluaupp
+```
+
+Or run without a global install:
+
+```bash
+npx cluaupp init my-game
+```
+
+## Quick start
+
+```bash
+cluaupp init my-game
+cd my-game
+cluaupp build
+rojo serve
+```
+
+Connect the Rojo plugin in Roblox Studio. Edit `src/**/*.{cpp,h,hpp}`, run `cluaupp watch` to rebuild on save.
+
+```
+src/server/*.server.cpp  →  out/server/LeaderStats/   Script + ModuleScripts
+src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript (or a service folder)
+src/shared/config.*      →  out/shared/Config.luau    typed config module
+```
+
+A tiny `leaderstats.server.cpp` becomes `Main` / `PlayersManager` / `CacheController`. A combat `.server.cpp` becomes `CombatController` with your `TakeDamage` logic. Filename tags: `.server.cpp`, `.client.cpp`, `.legacy.server.cpp`, `.legacy.client.cpp`, or no tag (ModuleScript). See [Architecture](docs/architecture.md).
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | Install, first project, Rojo, IntelliSense |
+| [**Docs + API (GitHub Pages)**](https://kartzrbx.github.io/Cluaupp/) | Site, Learn tab, every class / datatype / enum |
+| [Learn](https://kartzrbx.github.io/Cluaupp/learn/) | C++ subset, Luau output, safety, architecture |
+| [CLI](docs/cli.md) | `init`, `build`, `watch`, flags |
+| [Syntax](docs/syntax.md) | C++ subset → Luau (`local`, `const`, types) |
+| [Roblox API](docs/roblox-api.md) | Vector3, CFrame, UDim2, GetService, Instance.new |
+| [Architecture](docs/architecture.md) | PascalCase services, Types modules, not a 200-line dump |
+| [C++ types](docs/cpp-types.md) | Typing, `const`, safety, organization |
+| [Comparison](docs/comparison.md) | vs roblox-ts and WASM toolchains |
+| [Contributing](CONTRIBUTING.md) | Tests, layout, how to ship |
+
+## Programmatic API
+
+```js
+const { compileSource, compileService } = require("cluaupp");
+
+const luau = compileSource(
+	`void init() { print("ok"); }`,
+	"init.cpp",
+	{ strict: true },
+);
+
+const service = compileService(
+	cppSource,
+	"server/leaderstats.server.cpp",
+	{ relativeName: "server/leaderstats.server.cpp" },
+);
+// service.files → LeaderStats/Main.luau, PlayersManager, CacheController, Types
+```
+
+## License
+
+MIT

package/bin/cluau.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../src/cli.js");

package/bin/cluaupp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../src/cli.js");

package/docs/README.md

@@ -0,0 +1,20 @@
+# Cluaupp documentation
+
+1. [Intro](intro.md) — what Cluaupp is
+2. [Getting started](getting-started.md) — npm, Rojo, Wally
+3. [CLI](cli.md) — `init`, `build`, `watch`
+4. [Syntax](syntax.md) — C++ subset, `local`, `const`
+5. [C++ types](cpp-types.md) — primitives, Instances, `nullptr`
+6. [const](cpp-const.md) — immutability
+7. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
+8. [Organization](cpp-organization.md) — server / client / shared
+9. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, performance
+10. [Architecture](architecture.md) — PascalCase services, Types modules, vs roblox-ts dumps
+11. [Libraries](libraries.md) — Janitor, Promise, Net, Module3D, Twinkle, DataServiceV2
+12. [Roblox API](roblox-api.md) — Vector3, CFrame, UDim2, classes
+13. [Config](config.md) — `cluaupp.config.json`
+14. [Comparison](comparison.md) — roblox-ts and WASM
+
+Moonwave site (local): `npx moonwave dev`
+
+Full site + engine API: **[GitHub Pages](https://kartzrbx.github.io/Cluaupp/)**

package/docs/architecture.md

@@ -0,0 +1,110 @@
+---
+title: Architecture
+sidebar_position: 15
+---
+
+# Output treated as a Roblox system
+
+roblox-ts decides **what instance you get** from a filename **key** (the same idea as Rojo):
+
+| Key | Rojo instance |
+| --- | --- |
+| `*.server.ts` | Script |
+| `*.client.ts` | LocalScript |
+| no suffix | ModuleScript |
+
+Flamework then stamps a second key (`@Service` / `@Controller`) so the runtime knows the **role**. Cluaupp does both steps without decorators.
+
+1. **Tag** (filename) — where the code runs and whether it is a Script, LocalScript, ModuleScript, or a 1:1 “legacy” dump.
+2. **Intent** (AST) — what the code *is for*: players, cache, combat, input, UI, net, data, … scored from APIs and identifiers, the same idea as intent classification in program analysis (features from the tree, not a 200-line dump).
+
+Leaderstats was the example. A combat `.server.cpp` is a different system and gets Combat folders, not a fake CacheController.
+
+## File tags
+
+| Source | Meaning | Output |
+| --- | --- | --- |
+| `combat.server.cpp` | Server **system** | `Combat/` Script: `init.server.luau` + Main / Controllers / Types |
+| `hud.client.cpp` | Client **system** | `Hud/` LocalScript folder |
+| `boot.legacy.server.cpp` | Server script, no split | `boot.server.luau` (Rojo Script, `init()` still runs) |
+| `boot.legacy.client.cpp` | Client script, no split | `boot.client.luau` |
+| `damage.cpp` (no tag) | **Module** | `Damage.luau` ModuleScript `return { ... }` — does not auto-run |
+
+Trivial entry files (`init.client.cpp` that only `print`) stay a single LocalScript. The planner does not invent Managers for a hello-world.
+
+## How the planner reasons
+
+```
+filename key  →  server | client | module | legacy
+AST features  →  GetService, Instance.new, methods, identifiers
+intent scores →  combat:2, character:1, …
+roles         →  Main + Managers + Controllers + Types
+user functions→  kept in the matching Controller (not discarded)
+```
+
+Generated files start with that trace:
+
+```luau
+-- tag server → Script (service)
+-- intents combat:2, character:1
+-- roles Main, CombatController, CombatTypes
+```
+
+| Evidence in the C++ | Role |
+| --- | --- |
+| `PlayerAdded`, `GetPlayers` | `PlayersManager` (Janitor) |
+| `Folder` + `IntValue` / `StringValue` | `CacheController` |
+| `TakeDamage`, `Humanoid`, `Raycast` | `CombatController` (your functions) |
+| `UserInputService`, `InputBegan` | `InputController` |
+| `RemoteEvent`, `Net` | `NetController` |
+| `DataStore`, `DataService` | `DataController` |
+| Domain shapes / stats | `{Service}Types` (`export type`, `return {}`) |
+| Wiring | `Main.Start` / `Main.Stop` |
+
+If the C++ creates Coins/Level, CacheController is generated (higher quality than copying `CreateLeaderstats`). Combat logic is **not** rewritten into leaderstats — `ApplyDamage` stays in `CombatController.luau`.
+
+## What leaderstats becomes
+
+```
+src/server/leaderstats.server.cpp
+```
+
+```
+out/server/LeaderStats/
+  init.server.luau
+  Main.luau
+  PlayersManager.luau
+  CacheController.luau
+  LeaderStatsTypes.luau
+```
+
+## What combat becomes
+
+```
+src/server/combat.server.cpp   -- TakeDamage, Humanoid
+```
+
+```
+out/server/Combat/
+  init.server.luau
+  Main.luau
+  CombatController.luau    -- your ApplyDamage / OnHit
+  CombatTypes.luau
+```
+
+No PlayersManager unless you actually listen to players. No CacheController unless you actually create value Instances.
+
+## ForeverHD-style rules
+
+- PascalCase folders and modules; camelCase locals
+- `--!strict` everywhere
+- Public API `Start` / `Stop`
+- Janitor owns connections in the Manager
+- Types modules `return {}`
+- Transparent `require(script.Parent.X)`
+
+## Config
+
+`cluaupp.config.json`: `"architecture": true` (default). `"architecture": false` forces 1:1 dumps (or use `.legacy.server.cpp` / `.legacy.client.cpp` per file).
+
+See [organization](cpp-organization.md) and [comparison](comparison.md).

package/docs/cli.md

@@ -0,0 +1,69 @@
+# CLI
+
+```
+cluaupp <command> [folder]
+```
+
+If `[folder]` is omitted, the current directory is used.
+
+## `cluaupp init [folder]`
+
+Creates a game from the template:
+
+- `src/server`, `src/client`, `src/shared`
+- `cluaupp.config.json`
+- `default.project.json` (Rojo)
+- `include/cluaupp/roblox.hpp` (IntelliSense)
+- `.vscode/c_cpp_properties.json`
+
+```bash
+cluaupp init .
+cluaupp init my-game
+```
+
+## `cluaupp build [folder]`
+
+Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. Script files become PascalCase **service folders** (`LeaderStats/Main.luau`, `PlayersManager.luau`, `CacheController.luau`, `LeaderStatsTypes.luau`) plus `init.server.luau` for Rojo. Shared `const` headers become `Config.luau`.
+
+- `--!strict` on every module
+- `#include "file.h"` inlines that header into the current file
+- `#include <cluaupp/roblox.hpp>` is ignored
+- `.h` / `.hpp` with a sibling `.cpp` are not emitted twice
+- `new Folder(parent)` in a stats system becomes `CacheController.Ensure`
+- A parse error exits with code 1 and `file:line:column`
+
+```bash
+cluaupp build
+cluaupp build ./my-game
+```
+
+## `cluaupp watch [folder]`
+
+Runs a `build` and rebuilds when a `.cpp`, `.h`, or `.hpp` under `src/` changes. Parse errors are printed; the watcher stays alive.
+
+## `cluaupp --version` / `cluaupp -v`
+
+Prints the npm package version.
+
+## `cluaupp --help`
+
+Shows usage.
+
+## Suggested npm scripts
+
+```json
+{
+	"scripts": {
+		"build": "cluaupp build",
+		"watch": "cluaupp watch"
+	}
+}
+```
+
+In the Cluaupp development repo:
+
+```bash
+npm run build    # cluaupp build game
+npm run dev      # watch + Rojo
+npm run stop     # stop Rojo
+```

package/docs/comparison.md

@@ -0,0 +1,37 @@
+# Why Cluaupp
+
+## vs roblox-ts
+
+[roblox-ts](https://roblox-ts.com/) transpiles TypeScript → Luau. Cluaupp is the same idea for C++: one language merge, readable output, quality Roblox APIs.
+
+Both are source-to-source. Neither goes through WASM. Generated Luau calls the Roblox API directly.
+
+The difference is **what Studio receives**. roblox-ts stops at the filename key (`*.server.ts` → Script). Cluaupp uses that key **and** reads the AST so a combat system is not emitted as a fake leaderstats. See [Architecture](architecture.md).
+
+Current Luau has [`local`, `const`, and `--!strict`](https://luau.org/getting-started). Cluaupp emits that on purpose: `const int` in C++ becomes `const x = ...` in Luau.
+
+## vs C++ → WASM → Luau (RBX-CPP / Emscripten)
+
+Compiling real C++ to WASM and translating the binary to Luau works, but the cost shows up in the API:
+
+- Roblox methods become generic calls (`lua_call`, blobs)
+- `GetPlayers()` and `FindFirstChild()` do not come out as they do in Studio
+- Heavy toolchain: Emscripten, CMake, Python, tens of GB of cache
+
+Cluaupp skips that path. You write *script* C++ (the same mental subset as roblox-ts) and the compiler emits readable Luau.
+
+```cpp
+players->GetPlayers()
+player->FindFirstChild("leaderstats")
+GetService<Players>()
+```
+
+is exactly what Studio expects, not a parallel runtime.
+
+## When to use what
+
+| Goal | Tool |
+| --- | --- |
+| Game in TypeScript | roblox-ts |
+| Game in C++, clear Roblox API, Luau `--!strict` | **Cluaupp** |
+| Full native C++ (templates, STL, engines) | not Cluaupp today |

package/docs/config.md

@@ -0,0 +1,31 @@
+# Configuration
+
+File: `cluaupp.config.json` at the game root (next to `src/`).
+
+```json
+{
+	"rootDir": "src",
+	"outDir": "out",
+	"strict": true,
+	"architecture": true
+}
+```
+
+| Field | Default | Effect |
+| --- | --- | --- |
+| `rootDir` | `"src"` | Where the `.cpp` / `.h` / `.hpp` files live |
+| `outDir` | `"out"` | Where services and modules are written |
+| `strict` | `true` | Prefix `--!strict` on every generated file |
+| `architecture` | `true` | Emit PascalCase service folders (`LeaderStats/Main.luau`, …) instead of one dump per `.cpp` |
+
+If the file is missing, those defaults apply.
+
+## Rojo
+
+The template ships `default.project.json` mapping:
+
+- `out/server` → `ServerScriptService.Cluaupp`
+- `out/client` → `StarterPlayer.StarterPlayerScripts.Cluaupp`
+- `out/shared` → `ReplicatedStorage.Cluaupp`
+
+`*.server.luau` and `*.client.luau` files are classified by Rojo as Script and LocalScript. A folder with `init.server.luau` becomes a Script named after the folder (`LeaderStats`) with ModuleScript children (`Main`, `PlayersManager`, `CacheController`, `LeaderStatsTypes`).

package/docs/cpp-advanced.md

@@ -0,0 +1,71 @@
+---
+title: Advanced Cluaupp
+sidebar_position: 14
+---
+
+# Advanced Cluaupp
+
+The subset is intentional. What exists is enough for game scripts; what is missing is listed so you do not fight the compiler.
+
+## Supported
+
+- Functions, prototypes (headers only), `if` / `else` / `while` / range-`for`
+- `new Class(parent)`, `GetService<T>()`, `::` statics (`CFrame::lookAt`, `Enum::Material::Plastic`)
+- `->` methods and properties, `.` members, `Connect`
+- `const`, `auto`, `nullptr`, arithmetic, `&&` `||` `!=`
+- Quoted includes, `.h` / `.hpp` as sources
+- Libraries via `#include <cluaupp/libs/...>` → `require(CluauppLibs.*)`
+
+## Not supported (yet)
+
+Full C++: templates besides `GetService<T>`, `class` bodies as emitted types, `std::`, overloading as two runtimes, `switch`, C-style `for`, macros, pointer arithmetic.
+
+If you need a custom type, it is usually a **ModuleScript in shared** (a `.cpp` of functions) or a Wally package, not a C++ class the compiler would lower to a metatable.
+
+## `::` vs `:` vs `.`
+
+| C++ | Luau | When |
+| --- | --- | --- |
+| `CFrame::lookAt(a, b)` | `CFrame.lookAt(a, b)` | datatype / enum / module static |
+| `MathUtils::Lerp(a, b, t)` | `MathUtils.Lerp(a, b, t)` | Cluaupp module function |
+| `Module3D::Attach3D(frame, model)` | `Module3D:Attach3D(frame, model)` | Module3D’s colon API |
+| `player->FindFirstChild("x")` | `player:FindFirstChild("x")` | Instance method |
+| `player->Name` | `player.Name` | property |
+| `janitor->Add(conn)` | `janitor:Add(conn)` | library method |
+
+## Init
+
+If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau`. Use that as the Script / LocalScript entry. Shared modules should **not** define `init()` unless you want them to run on require.
+
+## Mixing extra Wally packages
+
+CluauppLibs already contains the full Janitor, Fusion, Cmdr, DataServiceV2, … systems (copied from GitHub into `runtime/`). Add Wally only for packages that are **not** in CluauppLibs. Headers in `include/cluaupp/libs/` match the shipped Luau.
+
+```cpp
+#include <cluaupp/libs/dataservice.hpp>
+
+void Grant(Player* player, int amount) {
+	auto coins = DataService::Get(player, "Currencies.Coins");
+	DataService::Set(player, "Currencies.Coins", coins + amount);
+}
+```
+
+Keep path strings in `config.h`. Match the tokens your DataServiceV2 template already uses (`DataService.Paths.Currencies.Coins` in Luau).
+
+## Performance notes
+
+- Prefer `const` and locals over recomputing in `RenderStepped`.
+- `Net` already uses `buffer`. Batch when you can; do not fire per-heartbeat for every NPC.
+- Module3D is a ViewportFrame — fine for shops and inventory, not for cloning the whole map (same advice as the [original Module3D thread](https://devforum.roblox.com/t/module3d-v61-viewportframe-implementation/207383)).
+- Janitor `Cleanup` is O(tracked objects). Link to the Instance that owns the scope instead of a global janitor for the whole server.
+
+## Good C++ conduct that still applies
+
+1. **Initialize everything.** `int coins;` without a value is a bug; write `int coins = 0`.
+2. **Small functions.** One behavior, named after the behavior.
+3. **No magic numbers.** `const int MAX_INVENTORY = 20`.
+4. **Early return.** Flatten `if` pyramids.
+5. **Headers declare, scripts define.** Prototypes in `.h`, bodies in `.cpp`.
+6. **Do not share mutable statics across server and client** — use Net or DataService.
+
+See also: [syntax](syntax.md), [libraries](libraries.md), [comparison](comparison.md).

package/docs/cpp-const.md

@@ -0,0 +1,52 @@
+---
+title: const and immutability
+sidebar_position: 11
+---
+
+# const and immutability
+
+A value that must not change should say so. In C++ that is `const`. Cluaupp emits Luau `const`, not `local x <const>`.
+
+```cpp
+const int STARTING_COINS = 0;
+const double GRAVITY = 196.2;
+```
+
+```luau
+const STARTING_COINS: number = 0
+const GRAVITY: number = 196.2
+```
+
+## Why it is a safety feature
+
+- Leaderstat starting values, product IDs, remote names, and animation speeds are configuration. If they are `local`, a later line can overwrite them by accident.
+- Reviewers see `const` and skip “could this mutate?”.
+- Luau `--!strict` rejects assignment to `const`.
+
+## What to keep mutable
+
+Player-owned numbers (`coins`, `combo`), UI state, and Janitor instances. Everything else defaults to `const` until you have a reason.
+
+```cpp
+const string REMOTE_COINS = "Coins";
+int coins = 0;
+
+void AddCoins(int amount) {
+	coins = coins + amount;
+}
+```
+
+`REMOTE_COINS` is a protocol name — immutable. `coins` is session state — mutable.
+
+## Immutability for tables and Instances
+
+`const` on a pointer does not freeze the Instance. `const Folder* stats` still has a mutable `Name` in Roblox. Treat “do not rebind the variable” and “do not mutate the object” as two separate decisions. For objects, prefer:
+
+- Create, parent, configure once, then only read.
+- Put mutations behind one function (`SetCoins`) instead of writing `coins.Value` from five scripts.
+
+## DataService paths
+
+Path tokens (`"Currencies.Coins"`) should be `const string` or a shared header. Never concatenate remote or datastore keys from user input.
+
+Next: [safety](cpp-safety.md).

package/docs/cpp-organization.md

@@ -0,0 +1,61 @@
+---
+title: Organization
+sidebar_position: 13
+---
+
+# Organization
+
+A Cluaupp game is laid out like a roblox-ts project on disk. The **output** is not a dump: `cluaupp build` turns each system into a PascalCase service folder (Main, Manager, Controller, Types). See [Architecture](architecture.md).
+
+```
+src/
+  server/     → Script (out/server)
+  client/     → LocalScript (out/client)
+  shared/     → ModuleScript (out/shared)
+include/cluaupp/   IntelliSense
+libs/              CluauppLibs (full Janitor, Fusion, Cmdr, DataService, …)
+Packages/          extra Wally packages only
+cluaupp.config.json
+default.project.json
+wally.toml
+```
+
+## Server / client / shared
+
+| Folder | Runs on | Allowed to |
+| --- | --- | --- |
+| `src/server` | Server | DataStore, DataService writes, `Net:Fire` |
+| `src/client` | Client | UI, Module3D, Twinkle, camera, `Net:FireServer` |
+| `src/shared` | Both | types, `const` config, FormatNumber, MathUtils |
+
+If a file needs `DataStoreService`, it is server. If it needs `UserInputService`, it is client. Shared code must compile in both.
+
+## Headers vs scripts
+
+- `.h` / `.hpp` in `src/` are inlined (`#include "config.h"`) and can hold `const` values and prototypes.
+- `#include <cluaupp/...>` is IntelliSense only — never inlined. `cluaupp build` copies those headers into the game `include/` folder. Cursor/clangd also reads `compile_flags.txt`.
+
+Keep config in `src/shared/config.h`:
+
+```cpp
+#pragma once
+const int STARTING_COINS = 0;
+const string REMOTE_COINS = "Coins";
+```
+
+## One module, one job
+
+`leaderstats.server.cpp` creates leaderstats. It does not also open the shop UI. Name files after the system: `inventory.server.cpp`, `shop.client.cpp`.
+
+`*.server.cpp` / `*.client.cpp` are **tags** (the same keys roblox-ts uses). Untagged `.cpp` is a ModuleScript. `.legacy.server.cpp` / `.legacy.client.cpp` skip the service split. See [Architecture](architecture.md).
+
+## CluauppLibs vs extra Wally
+
+| Need | Where |
+| --- | --- |
+| Janitor, Promise, Fusion, Iris, Cmdr, TopbarPlus, Chrono, DataServiceV2, EzVisualz, StateMachine, Spring, Display, Module3D, FormatNumber, Net, MathUtils, Twinkle | `CluauppLibs` (copied on `cluaupp build` from GitHub-vendored `runtime/`) |
+| Some other community package | `wally.toml` → `Packages` |
+
+Do not install a second Janitor from Wally unless you have a reason — CluauppLibs already has howmanysmall/Janitor. DataServiceV2 still bundles its own janitor/quicknet/signal inside the DataService folder.
+
+Next: [advanced Cluaupp](cpp-advanced.md).