cluaupp 1.0.0 → 1.4.0

package/docs/examples/data-boot.md

@@ -1,98 +0,0 @@
----
-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).

package/docs/examples/hud.md

@@ -1,28 +0,0 @@
----
-title: HUD
-sidebar_position: 6
----
-
-# HUD
-
-Live source: [`examples/game/src/client/hud.client.clpp`](../../examples/game/src/client/hud.client.clpp). Fusion API: [CL++](https://kartzrbx.github.io/CLPP/).
-
-Client-only (`[[client]]`). `Fusion:scoped` / `Fusion:Value` / `Fusion:Computed` / `Fusion:New` build a coins label. `guard` fails if `LocalPlayer` is missing.
-
-```clpp
-#include <clpp/roblox.clh>
-#include <clpp/libs/fusion.clh>
-
-[[client]]
-void init() {
-	Players* players = GetService<Players>();
-	Player* localPlayer = players.LocalPlayer;
-	guard (localPlayer != null) else {
-		report("LocalPlayer missing");
-		return;
-	}
-	auto scope = Fusion:scoped();
-	auto coins = Fusion:Value(scope, 0);
-	coins(100);
-}
-```

package/docs/examples/index.md

@@ -1,38 +0,0 @@
----
-title: Examples
-sidebar_position: 1
----
-
-# Examples
-
-High-quality Cluaupp systems you can copy. Each page is a full service in **CL++**. Live sample: [`examples/game`](../../examples/game). Language reference: [kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/).
-
-These are **not** dumps of `int main()`. Entry is `void init()`. Types are `struct` + `Class::` methods. Canonical Leaderstats: [handbook](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
-
-## Suggested layout
-
-```
-src/
-  shared/PlayerData.clh
-  shared/config.clp
-  shared/features.clp
-  server/leaderstats.server.clpp
-  server/combat.server.clpp
-  client/init.client.clpp
-  client/hud.client.clpp
-```
-
-Boot DataService **once**. Other services `WaitFor` after that.
-
-## Catalog
-
-| Example | Teaches |
-| --- | --- |
-| [Data boot](data-boot.md) | `Server.Init` / `Client.Init`, your Template, not `main()` |
-| [Leaderstats](leaderstats.md) | Folder `leaderstats`, FormatNumber, `GetChangedSignal`, per-player Janitor |
-| [Combat (server validation)](combat.md) | Client sends **intent**; server checks range, cooldown, health, then `TakeDamage` |
-| [Shop](shop.md) | `Net` buy remote, prices on the server, DataService debit |
-| [HUD](hud.md) | Client `WaitForData`, labels, Twinkle |
-| [Sword / Touched](sword.md) | Hitbox on the **server**, debounce, no client damage |
-
-Read with [Libraries](../libraries/index.md), [OOP structure](../oop/index.md), and [Safety](../cpp-safety.md).

package/docs/examples/leaderstats.md

@@ -1,69 +0,0 @@
----
-title: Leaderstats
-sidebar_position: 3
----
-
-# Leaderstats
-
-Canonical copy (three files): [Docs → Example: Leaderstats](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
-
-Roblox shows the player list from a Folder named exactly `leaderstats` under the Player. This service **creates** those values, then mirrors DataService coins into them.
-
-It does **not** call `DataService.Init`. Boot that in [Data boot](data-boot.md) with your `PlayerData` Template.
-
-## Files
-
-| File | Role |
-| --- | --- |
-| `shared/PlayerData.h` | Template structs (`Currencies.Coins`, inventory `LuaArray`) |
-| `server/LeaderstatsServer.h` | `struct LeaderstatsServer` — fields + method decls (same stem) |
-| `server/LeaderstatsServer.server.cpp` | `Class::` bodies + `void init()` |
-
-## Rules
-
-| Rule | Why |
-| --- | --- |
-| Same-stem header | `LeaderstatsServer.h` + `LeaderstatsServer.server.cpp`. A differently named `leaderstats.h` is a `require`. |
-| `.server.cpp` | Untagged cpp is a ModuleScript; `init()` will not run by itself. |
-| `Paths.Currencies.Coins` | After `Init`. A local `int Coins` is not a Data path. |
-| `string_concat` or string `+` | Luau `..`. Do not write `..` in the `.cpp`. |
-| Janitor keyed by player name | Leaving the game must `Destroy` the folder. |
-| Lambda or named function | `GetChangedSignal(...).Connect([coinsValue](int n) { ... })` is valid. |
-
-## Header
-
-```cpp
-#pragma once
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/janitor.hpp>
-#include <cluaupp/libs/dataservice.hpp>
-
-struct LeaderstatsServer {
-	static constexpr int STARTING_COINS = 0;
-	Janitor* janitor;
-	string GetPlayerJanitorKey(Player* player);
-	void UpdateLeaderstatsWithValues(IntValue* currentValue, int newValue);
-	Folder* EnsurePlayerLeaderstatsFolder(Player* player);
-	void PlayerEntered(Player* player);
-};
-```
-
-## `PlayerEntered`
-
-```cpp
-void LeaderstatsServer::PlayerEntered(Player* player) {
-	Folder* leaderstatsFolder = EnsurePlayerLeaderstatsFolder(player);
-	Data* playerData = DataService::Server.WaitFor(player);
-	IntValue* coinsValue = static_cast<IntValue*>(leaderstatsFolder->FindFirstChild("Coins"));
-	if (coinsValue) {
-		playerData->GetChangedSignal(DataService::Server.Paths.Currencies.Coins).Connect(
-			[coinsValue](int newValue) {
-				UpdateLeaderstatsWithValues(coinsValue, newValue);
-			}
-		);
-	}
-	janitor->Add(leaderstatsFolder, "Destroy", GetPlayerJanitorKey(player));
-}
-```
-
-`init()` constructs `LeaderstatsServer`, assigns `janitor = new Janitor()`, runs `PlayerEntered` for everyone already in the game, then `PlayerAdded` + `BindToClose`. Full listing is on the [handbook page](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).

package/docs/examples/shop.md

@@ -1,122 +0,0 @@
----
-title: Shop
-sidebar_position: 5
----
-
-# Shop
-
-The client sends **which product**. The server looks up the price, checks Money, then `Set`. Never let the client send the new balance or the price.
-
-## Catalog header
-
-`src/shared/constants/ShopCatalog.hpp`
-
-Cluaupp has no maps. A function with early returns is the catalog.
-
-```cpp
-#pragma once
-
-const int PRODUCT_HEALTH_PACK = 1;
-const int PRODUCT_SPEED_TOME = 2;
-
-int PriceOf(int productId) {
-	if (productId == PRODUCT_HEALTH_PACK) {
-		return 50;
-	}
-	if (productId == PRODUCT_SPEED_TOME) {
-		return 200;
-	}
-	return 0;
-}
-```
-
-`PriceOf` lives in a header so the **server** is the copy that matters. The client may include it for UI labels, but a patched client cannot change what the server charges.
-
-## Server — `ShopServer.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/ShopCatalog.hpp"
-
-Janitor* janitor = new Janitor();
-NetEvent* Buy = Net::Event("Buy");
-
-void ApplyProduct(Player* player, int productId) {
-	Model* character = player->Character;
-	if (character == nullptr) {
-		return;
-	}
-	Humanoid* humanoid = character->FindFirstChildOfClass("Humanoid");
-	if (humanoid == nullptr) {
-		return;
-	}
-	if (productId == PRODUCT_HEALTH_PACK) {
-		humanoid->Health = humanoid->MaxHealth;
-		return;
-	}
-	if (productId == PRODUCT_SPEED_TOME) {
-		humanoid->WalkSpeed = 24;
-		return;
-	}
-}
-
-void OnBuy(Player* player, int productId) {
-	int price = PriceOf(productId);
-	if (price < 1) {
-		cout::warn << "unknown product " << productId << endl;
-		return;
-	}
-	Data* data = DataService::Server.WaitFor(player);
-	if (data == nullptr) {
-		return;
-	}
-	int money = data->Get(DataService::Server.Paths.Currencies.Money);
-	if (money < price) {
-		cout::ping << player->Name << " cannot afford " << productId << endl;
-		return;
-	}
-	data->Set(DataService::Server.Paths.Currencies.Money, money - price);
-	ApplyProduct(player, productId);
-}
-
-void init() {
-	Buy->On(OnBuy);
-	janitor->Add(Buy);
-}
-```
-
-Debit **before** (or atomically with) the effect. If you grant the item first and the `Set` fails, the player dupes.
-
-## Client — `ShopClient.client.cpp`
-
-```cpp
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/janitor.hpp>
-#include <cluaupp/libs/net.hpp>
-#include "../../../shared/constants/ShopCatalog.hpp"
-
-Janitor* janitor = new Janitor();
-NetEvent* Buy = Net::Event("Buy");
-
-void OnHealthPackClicked() {
-	Buy->FireServer(PRODUCT_HEALTH_PACK);
-}
-
-void init() {
-	return;
-}
-```
-
-Wire `OnHealthPackClicked` to a `TextButton->MouseButton1Click.Connect(OnHealthPackClicked)` when you have the GUI. The remote payload is only the product id.
-
-## Rules
-
-- `productId < 1` / unknown id → `PriceOf` returns `0` → reject.
-- Do not `FireServer(price)` or `FireServer(newMoney)`.
-- [Leaderstats](leaderstats.md) updates from `GetChangedSignal` after `Set`.
-- Same Net name `"Buy"` on both sides.
-
-See [Safety](../cpp-safety.md).

package/docs/examples/sword.md

@@ -1,108 +0,0 @@
----
-title: Sword (Touched)
-sidebar_position: 7
----
-
-# Sword (Touched)
-
-Melee that uses a **server** `Touched` on the tool handle. The client can play animations; it must not tell the server how much damage to apply.
-
-Same authority as [combat](combat.md), without a Net remote: while the Tool is equipped, `Touched` runs on the server.
-
-## Config
-
-`src/shared/constants/SwordConfig.hpp`
-
-```cpp
-#pragma once
-
-const double SWORD_COOLDOWN = 0.35;
-const int SWORD_DAMAGE = 18;
-```
-
-## Script inside the Tool
-
-Put the source next to the Tool so `script->Parent` is the `Tool`. Use **`.legacy.server.cpp`** so Cluaupp emits a 1:1 Script (no Main/Controller split) that Rojo can parent under `ClassicSword`.
-
-`src/server/tools/Sword.legacy.server.cpp`
-
-```cpp
-#include <cluaupp/roblox.hpp>
-#include "../../shared/constants/SwordConfig.hpp"
-
-Players* Players = GetService<Players>();
-Tool* tool = script->Parent;
-
-void OnTouched(Instance* hit) {
-	if (hit == nullptr) {
-		return;
-	}
-
-	Player* attacker = Players->GetPlayerFromCharacter(tool->Parent);
-	if (attacker == nullptr) {
-		return;
-	}
-
-	NumberValue* last = attacker->FindFirstChild("LastSwordAt");
-	if (last != nullptr) {
-		if (tick() - last->Value < SWORD_COOLDOWN) {
-			return;
-		}
-	}
-
-	Instance* model = hit->FindFirstAncestorOfClass("Model");
-	if (model == nullptr) {
-		return;
-	}
-	Player* victim = Players->GetPlayerFromCharacter(model);
-	if (victim == nullptr) {
-		return;
-	}
-	if (victim == attacker) {
-		return;
-	}
-
-	Humanoid* humanoid = model->FindFirstChildOfClass("Humanoid");
-	if (humanoid == nullptr) {
-		return;
-	}
-	if (humanoid->Health <= 0) {
-		return;
-	}
-
-	if (last == nullptr) {
-		last = new NumberValue(attacker);
-		last->Name = "LastSwordAt";
-	}
-	last->Value = tick();
-	humanoid->TakeDamage(SWORD_DAMAGE);
-}
-
-void init() {
-	BasePart* handle = tool->FindFirstChild("Handle");
-	if (handle == nullptr) {
-		cout::warn << "ClassicSword missing Handle" << endl;
-		return;
-	}
-	handle->Touched.Connect(OnTouched);
-}
-```
-
-`tool->Parent` is the Character while equipped, `nil` in the backpack — `GetPlayerFromCharacter` then fails and the swing is ignored. That is what you want.
-
-## Why `.legacy`
-
-A tagged `Sword.server.cpp` in `src/server/` becomes a service folder in ServerScriptService. A Tool Script must live **under the Tool**. Legacy keeps one file you can Rojo-map into `ClassicSword`.
-
-## Rules
-
-| Do | Do not |
-| --- | --- |
-| `TakeDamage(SWORD_DAMAGE)` on the server | `FireServer(damage)` from a LocalScript |
-| Skip `victim == attacker` | Damage the owner when the handle clips their own parts |
-| Cooldown on the attacker | Trust `Touched` rate (it fires every physics step) |
-| `GetPlayerFromCharacter` | Treat every Humanoid as a player if you only want PvP |
-
-Client: a LocalScript in the same Tool can play an AnimationTrack on `Activated`. It still must not replicate a damage number.
-
-For ranged hits (mouse target → remote), use [combat](combat.md).

package/docs/getting-started.md

@@ -1,62 +0,0 @@
-# Getting started
-
-Cluaupp is the **game toolchain**. [CL++](https://kartzrbx.github.io/CLPP/) is the **language**.
-
-## Requirements
-
-- [Node.js](https://nodejs.org/) 18 or newer
-- [Rojo](https://rojo.space/) **7.7.0** (`cluaupp init` writes `rokit.toml`)
-- **`clpp` on PATH** from [KartzRbx/CLPP](https://github.com/KartzRbx/CLPP)
-
-```bash
-cargo install --path .   # inside a CL++ checkout
-clpp install             # VS Code / Cursor language pack
-```
-
-## Install Cluaupp
-
-```bash
-npm install -g cluaupp
-cluaupp --version
-```
-
-Or:
-
-```bash
-npx cluaupp init my-game
-```
-
-## First game
-
-```bash
-cluaupp init my-game
-cd my-game
-rokit install
-cluaupp build
-rojo serve
-```
-
-```
-my-game/
-  cluaupp.config.json
-  default.project.json
-  src/
-    server/leaderstats.server.clpp
-    client/init.client.clpp
-    shared/config.clp
-  out/                    ← generated Luau (do not edit)
-  libs/                   ← CluauppLibs
-```
-
-## Tiny program
-
-```clpp
-#include <clpp/roblox.clh>
-
-void init() {
-	Players* players = GetService<Players>();
-	post("online: " .: players::GetPlayers());
-}
-```
-
-Language course and reference: [kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/). Migrating `.cpp`: [migration](migration.md).

package/docs/intellisense.md

@@ -1,12 +0,0 @@
-# IntelliSense
-
-CL++ highlighting, completion, and diagnostics come from **`clpp install`** ([KartzRbx/CLPP](https://github.com/KartzRbx/CLPP) language pack). Cluaupp does not ship clangd or a C++ engine.
-
-```bash
-clpp install
-cluaupp intellisense   # writes files.associations for .clpp / .clp / .clh
-```
-
-Reload the editor. Language id is **`clpp`**, not `cpp`.
-
-`cluaupp lsp` can surface `clpp` compile errors over stdio; prefer the official CL++ extension for day-to-day editing.

package/docs/intro.md

@@ -1,38 +0,0 @@
----
-title: Cluaupp
-sidebar_position: 1
----
-
-# Cluaupp
-
-**CL++ on Roblox.** You write [CL++](https://kartzrbx.github.io/CLPP/). Cluaupp runs `clpp`, maps libraries into `ReplicatedStorage.CluauppLibs`, and syncs with Rojo.
-
-This site covers the **toolchain** (`init`, `build`, `watch`, libs). The language course is on the [CL++ site](https://kartzrbx.github.io/CLPP/).
-
-## What you get
-
-1. CLI: `cluaupp init` / `build` / `watch`
-2. First-party libraries in `ReplicatedStorage.CluauppLibs`
-3. Rojo project mapping (`out/server`, `out/client`, `out/shared`)
-
-## First program
-
-```clpp
-#include <clpp/roblox.clh>
-#include <clpp/libs/janitor.clh>
-
-void OnPlayer(Player* player) {
-	guard (player != null) else {
-		return;
-	}
-	Janitor* janitor = new Janitor();
-	janitor::LinkToInstance(player);
-}
-
-void init() {
-	Players* players = GetService<Players>();
-	players::PlayerAdded~>Connect(OnPlayer);
-}
-```
-
-Read [Getting started](getting-started.md), [syntax](syntax.md), and [migration](migration.md).

package/docs/libraries/_category_.json

@@ -1,5 +0,0 @@
-{
-	"label": "Libraries",
-	"position": 20,
-	"collapsed": false
-}

package/docs/libraries/dataservice.md

@@ -1,107 +0,0 @@
----
-title: DataService
-sidebar_position: 2
----
-
-# DataService
-
-Player profiles (DataServiceV2). Header: `#include <cluaupp/libs/dataservice.hpp>`.
-
-The **save shape is yours**. Do not put `Currencies` / `Money` on the library `DataPath` type. Define a struct in the game (shared header) and pass it as `.Template`.
-
-## 1. Template (shared)
-
-```cpp
-#pragma once
-
-struct TemplateData {
-	struct Currencies {
-		int Money = 0;
-		int Level = 1;
-	} Currencies;
-};
-```
-
-Luau `DataService.Paths` follows this table (`Paths.Currencies.Money`).
-
-## 2. Start the server
-
-Call **once** from a server boot script (`DataBoot.server.cpp`). `void init()` is what Cluaupp runs (not `int main()`).
-
-```cpp
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/dataservice.hpp>
-#include "../../shared/constants/TemplateData.hpp"
-
-void init() {
-	TemplateData playerData = TemplateData {};
-	DataService::Server.Init(DataServiceOptions {
-		.Template = playerData,
-		.StoreName = "PlayerData",
-		.UseMock = true,
-	});
-}
-```
-
-| Field | Meaning |
-| --- | --- |
-| `.Template` | Default document. Must match the save struct. |
-| `.StoreName` | DataStore name (or a version string you own). |
-| `.UseMock` | `true` in Studio / tests so you do not hit the live store. |
-| `.KeyPrefix` | Optional prefix on profile keys. |
-| `.StrictPaths` | Reject unknown path segments. |
-| `.AutoCreateMissingTables` | Create missing nested tables on write. |
-
-## 3. Start the client
-
-```cpp
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/dataservice.hpp>
-
-void init() {
-	DataService::Client.Init();
-}
-```
-
-## 4. Read / wait
-
-```cpp
-Data* data = DataService::Server.WaitFor(player);
-if (data == nullptr) {
-	return;
-}
-
-int money = data->Get(DataService::Server.Paths.Currencies.Money);
-```
-
-- `WaitFor` — yield until the profile exists.
-- `Get(player)` — already loaded or `nullptr`.
-- `data->Get()` with no path — whole table.
-- `GetPersisted` / `GetTransient` — saved vs session-only.
-
-Client: `DataService::Client.WaitForData()` / `Get()`.
-
-## 5. Write and listen
-
-```cpp
-data->Set(DataService::Server.Paths.Currencies.Money, 10);
-
-void OnCurrenciesChanged() {
-	return;
-}
-
-data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged);
-data->GetChangedSignal(DataService::Server.Paths.Currencies.Coins).Connect([](int coins) {
-	print(coins);
-});
-```
-
-`GetChangedSignal` fires when that path (or a child) changes. Use a named function or a lambda (`[](int newValue) { ... }`).
-
-## Rules
-
-- Init on **server and client**. Writes that must persist belong on the server.
-- Paths are not a C++ enum in the library. They exist because your Template was passed to `Init`.
-- Keep boot (`Init`) in one file. Keep HUD / leaderstats in another and `WaitFor` there.
-
-Full copies: [Data boot](../examples/data-boot.md), [Leaderstats](../examples/leaderstats.md), [HUD](../examples/hud.md).