cluaupp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,10 +1,29 @@
 # Changelog
 
+## 0.1.4
+
+- Quoted `#include "Header.h"` of project files becomes `const Header = require(...)`. Header-only structs emit a constructor (`TemplateData()`); const headers bind `PLAYER_DATA_VERSION` from the module. Boot scripts require services (`LeaderstatsServer:init()`).
+- Keep `const` for injected `require` / `GetService` and `const function` for C++ functions (not `local`).
+
+## 0.1.3
+
+- Architecture: generated services keep a fixed declaration order (requires, types, constants, variables, functions, cleanup, return) without section banners. Domain `Stop` runs `janitor:Cleanup()`.
+- IntelliSense: `cluaupp init` / `cluaupp intellisense` install Microsoft `ms-vscode.cpptools` (VSIX on Cursor, where the marketplace omits it), write `.vscode/c_cpp_properties.json` (LLVM clang++, C++20, `include/` + `src/`, `compile_commands.json`), and disable clangd so the two engines do not fight. `build`/`watch` only refresh `compile_commands.json`.
+- `Class::method` on game types becomes `Class:method()` (`self`). Datatype/library statics stay dotted (`CFrame.lookAt`, `Color3.fromRGB`, `FormatNumber.Abbreviate`).
+- `switch` / `case` / `default` / `break` compile to a one-shot `repeat` with `if` / `elseif` / `else`. The discriminant is evaluated once; stacked `case` labels share a body; `break` leaves the switch even from inside an `if`.
+- Janitor typed border re-exports `_impl` (`export type Janitor = Impl.Janitor; return Impl`). It no longer invents `Has` or requires Promise for a parallel type that did not match howmanysmall.
+- Emit: injected `require` / `GetService` are `const`. C++ functions emit as `const function` instead of `local function`.
+- `.server.cpp` emits `init.luau` + `init.meta.json` with `RunContext.Server`. `init.server.luau` is Legacy and is pruned.
+- `cout << ... << endl` emits `print(...)`. `cerr <<` emits `warn`. `cout::print` / `cout::warn` / `cout::error` / `cout::ping` map to the Roblox globals.
+- Docs: [print and cout](docs/print-cout.md); [Libraries](docs/libraries/index.md) how-tos (DataService Init, Janitor, Promise, Net); [OOP structure](docs/oop/index.md) (file tags, services, modules); [Examples](docs/examples/index.md) (leaderstats, combat validation, shop, HUD, sword). GitHub Pages Learn tabs: OOP, Libraries, print/cout, Examples — generated into `site/` (`guide/oop.html`, `guide/examples.html`).
+
 ## 0.1.2
 
 - Watch does not write `out/` while any file fails to compile (Studio keeps the last good scripts).
 - Watch/build skip rewriting Luau whose contents did not change (a space in C++ no longer floods Rojo).
-- `libs/` is fill-only: missing files are restored, existing files are never overwritten or deleted. Fixes Rojo 7 crashing on `libs/ArrayIndexer` when watch/build raced a live serve.
+- Watch never copies `libs/` or headers. Changing a constant no longer makes Rojo 7 crash on `libs/ArrayIndexer`.
+- `libs/` on `cluaupp build` is fill-only: missing files are restored, existing files are never overwritten or deleted.
+- Filename tags: `.server.cpp` → Script (`init.server.luau`), `.client.cpp` → LocalScript (`init.client.luau`), `.plugin.cpp` → Plugin, `.legacy` / `.legacy.client` / `.legacy.server` → Legacy. Bare `init.luau` is not used for `.server` (Rojo would make a ModuleScript).
 - Dropped `$optional` from `default.project.json` (Rojo 7.7 failed to deserialize it).
 
 ## 0.1.1

package/README.md

@@ -8,13 +8,6 @@
 
 [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)
@@ -78,7 +71,7 @@ src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript (or a servic
 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).
+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) and [OOP structure](docs/oop/index.md).
 
 ## Documentation
 
@@ -89,8 +82,12 @@ A tiny `leaderstats.server.cpp` becomes `Main` / `PlayersManager` / `CacheContro
 | [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) |
+| [print and cout](docs/print-cout.md) | `cout <<`, `cout::warn`, `endl` |
 | [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 |
+| [OOP structure](docs/oop/index.md) | File tags, services, modules, structs |
+| [Libraries](docs/libraries/index.md) | DataService Init, Janitor, Promise, Net |
+| [Examples](docs/examples/index.md) | Leaderstats, combat validation, shop, HUD, sword |
 | [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 |

package/docs/README.md

@@ -4,16 +4,19 @@
 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
+5. [print and cout](print-cout.md) — `cout <<`, `cout::warn`, `endl`
+6. [C++ types](cpp-types.md) — primitives, Instances, `nullptr`
+7. [const](cpp-const.md) — immutability
+8. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
+9. [Organization](cpp-organization.md) — server / client / shared
+10. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, performance
+11. [Architecture](architecture.md) — PascalCase services, Types modules, vs roblox-ts dumps
+12. [OOP structure](oop/index.md) — file tags, services, modules, structs
+13. [Libraries](libraries/index.md) — DataService Init, Janitor, Promise, Net, more
+14. [Examples](examples/index.md) — leaderstats, combat validation, shop, HUD, sword
+15. [Roblox API](roblox-api.md) — Vector3, CFrame, UDim2, classes
+16. [Config](config.md) — `cluaupp.config.json`
+17. [Comparison](comparison.md) — roblox-ts and WASM
 
 Moonwave site (local): `npx moonwave dev`
 

package/docs/architecture.md

@@ -24,13 +24,16 @@ Leaderstats was the example. A combat `.server.cpp` is a different system and ge
 
 | 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 |
+| `combat.server.cpp` | **Script** RunContext Server | `Combat/init.luau` + `init.meta.json` |
+| `hud.client.cpp` | **LocalScript** | `Hud/init.client.luau` |
+| `tools.plugin.cpp` | **Script** RunContext Plugin | `Tools/init.luau` + `init.meta.json` |
+| `boot.legacy.cpp` | Legacy Script | `boot.server.luau` |
+| `boot.legacy.server.cpp` | Legacy Script | `boot.server.luau` |
+| `boot.legacy.client.cpp` | Legacy LocalScript | `boot.client.luau` |
+| `boot.legacy.plugin.cpp` | Plugin | `boot.luau` + Plugin meta |
+| `damage.cpp` (no tag) | **ModuleScript** | `Damage.luau` |
 
-Trivial entry files (`init.client.cpp` that only `print`) stay a single LocalScript. The planner does not invent Managers for a hello-world.
+Trivial entry files (`init.client.cpp` that only `print`) stay a single LocalScript (`init.client.luau`). The planner does not invent Managers for a hello-world.
 
 ## How the planner reasons
 
@@ -63,6 +66,8 @@ Generated files start with that trace:
 
 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`.
 
+The domain controller keeps **every** user function. CacheController is generated beside it; it must not delete `SetupPlayerManager` while `init` still calls that name. `GetChangedSignal(Paths.Currencies)` stays in `DataController`.
+
 ## What leaderstats becomes
 
 ```
@@ -71,7 +76,8 @@ src/server/leaderstats.server.cpp
 
 ```
 out/server/LeaderStats/
-  init.server.luau
+  init.luau
+  init.meta.json
   Main.luau
   PlayersManager.luau
   CacheController.luau
@@ -86,7 +92,8 @@ src/server/combat.server.cpp   -- TakeDamage, Humanoid
 
 ```
 out/server/Combat/
-  init.server.luau
+  init.luau
+  init.meta.json
   Main.luau
   CombatController.luau    -- your ApplyDamage / OnHit
   CombatTypes.luau
@@ -98,13 +105,13 @@ No PlayersManager unless you actually listen to players. No CacheController unle
 
 - PascalCase folders and modules; camelCase locals
 - `--!strict` everywhere
-- Public API `Start` / `Stop`
+- Public API `Start` / `Stop`. `Start` is idempotent (`Stop` first). Domain `Stop` is `janitor:Cleanup()` (unbind, janitor stays reusable). `OnClose` / `Destroy` stay for `BindToClose`. `PlayersManager.Stop` disconnects and runs `onLeave`. `CacheController.ClearAll` drops the cache.
 - Janitor owns connections in the Manager
-- Types modules `return {}`
+- Module layout in generated Luau (no section banners): requires, types, constants, variables, functions, cleanup, 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).
+How to **write** a service, tags, and module-style OOP: [OOP structure](oop/index.md). Copy-paste systems: [Examples](examples/index.md). Also [organization](cpp-organization.md) and [comparison](comparison.md).

package/docs/cli.md

@@ -23,7 +23,7 @@ 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`.
+Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. Script files become PascalCase **service folders** (`LeaderStats/Main.luau`, `PlayersManager.luau`, `CacheController.luau`, `LeaderStatsTypes.luau`) plus `init.luau` and `init.meta.json` (`RunContext.Server`) for Rojo. Shared `const` headers become `Config.luau`.
 
 - `--!strict` on every module
 - `#include "file.h"` inlines that header into the current file
@@ -41,7 +41,7 @@ cluaupp build ./my-game
 
 ## `cluaupp watch [folder]`
 
-Runs a `build` and rebuilds when anything under `src/` changes, including deletes. Parse errors are printed; the watcher stays alive and **does not write `out/`** until the project compiles cleanly (Studio keeps the last good scripts). Rebuilds are debounced and do **not** recopy `libs/`. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
+Runs a compile (without copying `libs/`) and rebuilds when anything under `src/` changes, including deletes. Parse errors are printed; the watcher stays alive and **does not write `out/`** until the project compiles cleanly (Studio keeps the last good scripts). A second watcher in the same game exits. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
 
 ## `cluaupp --version` / `cluaupp -v`
 

package/docs/config.md

@@ -28,4 +28,4 @@ The template ships `default.project.json` mapping:
 - `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`).
+`*.server.cpp` becomes a folder with `init.luau` + `init.meta.json` (`className` Script, `RunContext` Server). `.client` stays LocalScript via `init.client.luau`. A `.legacy.server.cpp` dump is still `*.server.luau` (Legacy).

package/docs/cpp-advanced.md

@@ -9,7 +9,7 @@ The subset is intentional. What exists is enough for game scripts; what is missi
 
 ## Supported
 
-- Functions, prototypes (headers only), `if` / `else` / `while` / range-`for`
+- Functions, prototypes (headers only), `if` / `else` / `while` / range-`for` / `switch` (`case`, `default`, `break`)
 - `new Class(parent)`, `GetService<T>()`, `::` statics (`CFrame::lookAt`, `Enum::Material::Plastic`)
 - `->` methods and properties, `.` members, `Connect`
 - `const`, `auto`, `nullptr`, arithmetic, `&&` `||` `!=`
@@ -18,7 +18,7 @@ The subset is intentional. What exists is enough for game scripts; what is missi
 
 ## 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.
+Full C++: templates besides `GetService<T>`, `class` bodies as emitted types, `std::`, overloading as two runtimes, 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.
 
@@ -45,12 +45,16 @@ CluauppLibs already contains the full Janitor, Fusion, Cmdr, DataServiceV2, …
 #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);
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		return;
+	}
+	int coins = data->Get(DataService::Server.Paths.Currencies.Money);
+	data->Set(DataService::Server.Paths.Currencies.Money, coins + amount);
 }
 ```
 
-Keep path strings in `config.h`. Match the tokens your DataServiceV2 template already uses (`DataService.Paths.Currencies.Coins` in Luau).
+`Paths.Currencies.Money` exists because **your** Template passed to `Init` had that field. Full copies: [Examples](examples/index.md).
 
 ## Performance notes
 
@@ -68,4 +72,4 @@ Keep path strings in `config.h`. Match the tokens your DataServiceV2 template al
 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).
+See also: [syntax](syntax.md), [print and cout](print-cout.md), [libraries](libraries/index.md), [OOP](oop/index.md), [examples](examples/index.md), [comparison](comparison.md).

package/docs/cpp-organization.md

@@ -47,7 +47,7 @@ const string REMOTE_COINS = "Coins";
 
 `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).
+`*.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) and [OOP structure](oop/index.md).
 
 ## CluauppLibs vs extra Wally
 
@@ -58,4 +58,6 @@ const string REMOTE_COINS = "Coins";
 
 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.
 
+How-tos: [Libraries](libraries/index.md). Service layout: [OOP](oop/index.md). Copy-paste: [Examples](examples/index.md).
+
 Next: [advanced Cluaupp](cpp-advanced.md).

package/docs/cpp-safety.md

@@ -9,7 +9,7 @@ Safety in Cluaupp is not a sandbox flag. It is a set of habits the compiler and
 
 ## 1. Never trust the client
 
-[Net](libraries.md) lets a client `FireServer`. The server must validate:
+[Net](libraries/net.md) lets a client `FireServer`. The server must validate:
 
 ```cpp
 void OnBuy(Player* player, int productId) {
@@ -17,19 +17,23 @@ void OnBuy(Player* player, int productId) {
 		return;
 	}
 	int price = PriceOf(productId);
-	int coins = DataService::Get(player, "Currencies.Coins");
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		return;
+	}
+	int coins = data->Get(DataService::Server.Paths.Currencies.Money);
 	if (coins < price) {
 		return;
 	}
-	DataService::Set(player, "Currencies.Coins", coins - price);
+	data->Set(DataService::Server.Paths.Currencies.Money, coins - price);
 }
 ```
 
-Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`).
+Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`). Full systems: [Shop](examples/shop.md), [Combat](examples/combat.md).
 
 ## 2. Clean up with Janitor
 
-Every `Connect` that outlives a player, a GUI, or a tool needs a Janitor. Leaving a step, destroying a character, or closing a menu should `Cleanup()` or `LinkToInstance`.
+Every `Connect` that outlives a player, a GUI, or a tool needs a [Janitor](libraries/janitor.md). Leaving a step, destroying a character, or closing a menu should `Cleanup()` or `LinkToInstance`.
 
 ```cpp
 auto* janitor = new Janitor();
@@ -45,7 +49,7 @@ Leaked connections duplicate effects: double coins, stacked cameras, lingering h
 
 ## 4. One writer for persisted data
 
-[DataServiceV2](https://wally.run/package/kartzrbx/dataservicev2) distinguishes `Get()` (merged, includes transient admin overlays) from `GetPersisted()` (what ProfileStore will save). Use `SetTransient` for test panels so you never persist cheat values. Only the server writes persisted paths.
+[DataService](libraries/dataservice.md) distinguishes `Get()` (merged, includes transient admin overlays) from `GetPersisted()` (what ProfileStore will save). Use `SetTransient` for test panels so you never persist cheat values. Only the server writes persisted paths. The save **shape** is your Template — the library does not ship `Currencies`.
 
 ## 5. Buffers, not ad-hoc strings
 
@@ -55,4 +59,4 @@ Leaked connections duplicate effects: double coins, stacked cameras, lingering h
 
 Remote names (`Net::Event("Coins")`) are public protocol. Keep them `const`, short, and unique. Changing a name without a migration breaks old clients.
 
-Next: [organization](cpp-organization.md).
+Next: [organization](cpp-organization.md), [OOP](oop/index.md), [Examples](examples/index.md).

package/docs/cpp-types.md

@@ -46,7 +46,7 @@ player.Name = "Kartz"
 player:FindFirstChild("leaderstats")
 ```
 
-There is no pointer arithmetic, no `delete`, no `std::unique_ptr`. Lifetime is Roblox’s: parented Instances live until `Destroy` or until a [Janitor](libraries.md) cleans them.
+There is no pointer arithmetic, no `delete`, no `std::unique_ptr`. Lifetime is Roblox’s: parented Instances live until `Destroy` or until a [Janitor](libraries/janitor.md) cleans them.
 
 ## `nullptr`
 

package/docs/examples/_category_.json

@@ -0,0 +1,5 @@
+{
+	"label": "Examples",
+	"position": 21,
+	"collapsed": false
+}

package/docs/examples/combat.md

@@ -0,0 +1,239 @@
+---
+title: Combat (server validation)
+sidebar_position: 4
+---
+
+# Combat (server validation)
+
+The client never sends **damage**. It sends **who I want to hit**. The server decides range, cooldown, alive state, and the damage constant.
+
+Pair with [Data boot](data-boot.md) if a kill should grant Money.
+
+## Shared config
+
+`src/shared/constants/CombatConfig.hpp`
+
+```cpp
+#pragma once
+
+const double ATTACK_RANGE = 12;
+const double ATTACK_COOLDOWN = 0.4;
+const int ATTACK_DAMAGE = 12;
+const int KILL_REWARD = 5;
+```
+
+Keep numbers in a header. Both server and client can include range for FX; **only the server** applies `TakeDamage`.
+
+## Server — `CombatServer.server.cpp`
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/net.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+#include "../../../shared/constants/CombatConfig.hpp"
+
+Players* Players = GetService<Players>();
+Janitor* janitor = new Janitor();
+NetEvent* Attack = Net::Event("Attack");
+
+BasePart* RootPart(Model* character) {
+	if (character == nullptr) {
+		return nullptr;
+	}
+	return character->FindFirstChild("HumanoidRootPart");
+}
+
+Humanoid* HumanoidOf(Model* character) {
+	if (character == nullptr) {
+		return nullptr;
+	}
+	return character->FindFirstChildOfClass("Humanoid");
+}
+
+bool InRange(Model* a, Model* b, double maxRange) {
+	BasePart* rootA = RootPart(a);
+	BasePart* rootB = RootPart(b);
+	if (rootA == nullptr) {
+		return false;
+	}
+	if (rootB == nullptr) {
+		return false;
+	}
+	Vector3 delta = rootA->Position - rootB->Position;
+	if (delta.Magnitude > maxRange) {
+		return false;
+	}
+	return true;
+}
+
+bool OnCooldown(Player* attacker) {
+	NumberValue* last = attacker->FindFirstChild("LastAttackAt");
+	if (last == nullptr) {
+		return false;
+	}
+	if (tick() - last->Value < ATTACK_COOLDOWN) {
+		return true;
+	}
+	return false;
+}
+
+void MarkAttack(Player* attacker) {
+	NumberValue* last = attacker->FindFirstChild("LastAttackAt");
+	if (last == nullptr) {
+		last = new NumberValue(attacker);
+		last->Name = "LastAttackAt";
+	}
+	last->Value = tick();
+}
+
+void RewardKill(Player* attacker) {
+	Data* data = DataService::Server.Get(attacker);
+	if (data == nullptr) {
+		return;
+	}
+	int money = data->Get(DataService::Server.Paths.Currencies.Money);
+	data->Set(DataService::Server.Paths.Currencies.Money, money + KILL_REWARD);
+}
+
+void OnAttack(Player* attacker, int targetUserId) {
+	if (attacker == nullptr) {
+		return;
+	}
+	if (targetUserId < 1) {
+		return;
+	}
+	if (OnCooldown(attacker)) {
+		return;
+	}
+
+	Player* target = Players->GetPlayerByUserId(targetUserId);
+	if (target == nullptr) {
+		return;
+	}
+	if (target == attacker) {
+		return;
+	}
+
+	Model* attackerChar = attacker->Character;
+	Model* targetChar = target->Character;
+	Humanoid* attackerHum = HumanoidOf(attackerChar);
+	Humanoid* targetHum = HumanoidOf(targetChar);
+	if (attackerHum == nullptr) {
+		return;
+	}
+	if (targetHum == nullptr) {
+		return;
+	}
+	if (attackerHum->Health <= 0) {
+		return;
+	}
+	if (targetHum->Health <= 0) {
+		return;
+	}
+	if (InRange(attackerChar, targetChar, ATTACK_RANGE) == false) {
+		cout::ping << attacker->Name << " out of range" << endl;
+		return;
+	}
+
+	MarkAttack(attacker);
+	double healthBefore = targetHum->Health;
+	targetHum->TakeDamage(ATTACK_DAMAGE);
+	if (healthBefore > 0) {
+		if (targetHum->Health <= 0) {
+			RewardKill(attacker);
+		}
+	}
+}
+
+void init() {
+	Attack->On(OnAttack);
+	janitor->Add(Attack);
+}
+```
+
+## Client — `CombatClient.client.cpp`
+
+The LocalScript only picks a target and fires. It does **not** pass `ATTACK_DAMAGE`.
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/net.hpp>
+
+Players* Players = GetService<Players>();
+UserInputService* UserInput = GetService<UserInputService>();
+Janitor* janitor = new Janitor();
+NetEvent* Attack = Net::Event("Attack");
+
+Player* PlayerFromPart(Instance* part) {
+	if (part == nullptr) {
+		return nullptr;
+	}
+	Instance* model = part->FindFirstAncestorOfClass("Model");
+	if (model == nullptr) {
+		return nullptr;
+	}
+	Player* fromModel = Players->GetPlayerFromCharacter(model);
+	if (fromModel != nullptr) {
+		return fromModel;
+	}
+	Instance* outer = model->FindFirstAncestorOfClass("Model");
+	if (outer == nullptr) {
+		return nullptr;
+	}
+	return Players->GetPlayerFromCharacter(outer);
+}
+
+void OnInputBegan(InputObject* input, bool gameProcessed) {
+	if (gameProcessed) {
+		return;
+	}
+	if (input->UserInputType != Enum::UserInputType::MouseButton1) {
+		return;
+	}
+	Player* localPlayer = Players->LocalPlayer;
+	if (localPlayer == nullptr) {
+		return;
+	}
+	Mouse* mouse = localPlayer->GetMouse();
+	if (mouse == nullptr) {
+		return;
+	}
+	Player* target = PlayerFromPart(mouse->Target);
+	if (target == nullptr) {
+		return;
+	}
+	if (target == localPlayer) {
+		return;
+	}
+	Attack->FireServer(target->UserId);
+}
+
+void init() {
+	janitor->Add(UserInput->InputBegan.Connect(OnInputBegan));
+}
+```
+
+## What the server rejects
+
+| Client cheat | Server check |
+| --- | --- |
+| `FireServer(99999)` damage | Damage is `ATTACK_DAMAGE` in the header — not an argument |
+| Hit a player across the map | `delta.Magnitude > ATTACK_RANGE` |
+| Spam click | `LastAttackAt` + `ATTACK_COOLDOWN` |
+| Target userId `0` / self | `targetUserId < 1`, `target == attacker` |
+| Hit a dead / missing character | Humanoid nil or `Health <= 0` |
+| Fire before spawn | `Character` / `HumanoidRootPart` missing |
+
+`Net::Event("Attack")` must be the **same string** on both sides. Treat that name as public protocol.
+
+## Cooldown storage
+
+`LastAttackAt` is a `NumberValue` on the Player: session-only, no DataStore. Do not persist combat cadence. For anti-exploit that must survive respawn, use DataService `SetTransient` on a path **you** added to the Template — still not a library field.
+
+## No lambdas
+
+`Attack->On(OnAttack)` needs a named function. The first argument of a server `On` is the `Player` who fired.
+
+See [Net](../libraries/net.md) and [Safety](../cpp-safety.md).

package/docs/examples/data-boot.md

@@ -0,0 +1,98 @@
+---
+title: Data boot
+sidebar_position: 2
+---
+
+# Data boot
+
+Start DataService **once** on the server and once on the client. Gameplay scripts (`leaderstats`, combat, shop) only `WaitFor` — they do not call `Init`.
+
+The save **shape is yours**. Do not put `Currencies` on the library `DataPath` type. Put it on a shared struct and pass that as `.Template`.
+
+## Shared template
+
+`src/shared/constants/TemplateData.hpp`
+
+```cpp
+#pragma once
+
+struct TemplateData {
+	struct Currencies {
+		int Money = 0;
+		int Level = 1;
+	} Currencies;
+};
+```
+
+`src/server/configurations/PlayerDataVersion.hpp`
+
+```cpp
+#pragma once
+
+const string PLAYER_DATA_VERSION = "PlayerData_v1";
+```
+
+Bump the store name when you **intentionally** wipe saves. Changing a field default in `TemplateData` does not migrate old profiles by itself.
+
+## Server — `DataBoot.server.cpp`
+
+Use `void init()`, not `int main()`. Cluaupp only auto-calls `init()`.
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+#include "../../shared/constants/TemplateData.hpp"
+#include "../configurations/PlayerDataVersion.hpp"
+
+void init() {
+	TemplateData playerData = TemplateData {};
+	DataService::Server.Init(DataServiceOptions {
+		.Template = playerData,
+		.StoreName = PLAYER_DATA_VERSION,
+		.UseMock = true,
+	});
+}
+```
+
+| Field | In production |
+| --- | --- |
+| `.Template` | Same struct the rest of the game reads through `Paths` |
+| `.StoreName` | Stable DataStore name (version it when you wipe) |
+| `.UseMock` | `true` in Studio so you do not hit the live store |
+
+After `Init`, `DataService::Server.Paths.Currencies.Money` exists because the Template had that table — not because the library shipped those fields.
+
+## Client — `DataBoot.client.cpp`
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+
+void init() {
+	DataService::Client.Init();
+}
+```
+
+Client `Init` has no Template. The server already owns the document.
+
+## What other scripts do
+
+```cpp
+Data* data = DataService::Server.WaitFor(player);
+if (data == nullptr) {
+	return;
+}
+
+int money = data->Get(DataService::Server.Paths.Currencies.Money);
+```
+
+- Server gameplay: `WaitFor(player)` then `Get` / `Set`.
+- Client HUD: `WaitForData()` then `Get`.
+- Never `Init` twice. A second `Init` fights the first store.
+
+## File tags
+
+`DataBoot.server.cpp` → Script **RunContext Server** (`init.luau` + `init.meta.json`).  
+`DataBoot.client.cpp` → LocalScript (`init.client.luau`).
+
+See [file tags](../oop/file-tags.md).