cluaupp 0.1.2 → 0.1.4

package/docs/libraries/dataservice.md

@@ -0,0 +1,104 @@
+---
+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);
+```
+
+`GetChangedSignal` fires when that path (or a child) changes. Cluaupp has no lambdas — use a named function.
+
+## 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).

package/docs/libraries/index.md

@@ -0,0 +1,22 @@
+---
+title: Using libraries
+sidebar_position: 1
+---
+
+# Libraries
+
+`#include <cluaupp/libs/...hpp>` is IntelliSense. `cluaupp build` copies the real Luau into `libs/` (`ReplicatedStorage.CluauppLibs`). You do not `require` by hand in C++.
+
+| Guide | Use it when |
+| --- | --- |
+| [DataService](dataservice.md) | Player save data, `Init`, `WaitFor`, `GetChangedSignal` |
+| [Janitor](janitor.md) | Connections, instances, cleanup on leave |
+| [Promise](promise.md) | Delay, Then / Catch / Await |
+| [Net](net.md) | RemoteEvent / RemoteFunction without making remotes |
+| [More libraries](more.md) | FormatNumber, Fusion, Cmdr, Twinkle, MathUtils, … |
+
+Sources: [runtime/SOURCES.md](https://github.com/KartzRbx/Cluaupp/blob/main/runtime/SOURCES.md). Re-vendor: `node scripts/vendor-libs.js`.
+
+Wally is optional. Do not install a second Janitor from Wally — CluauppLibs already has howmanysmall/Janitor.
+
+Copy-paste systems: [Examples](../examples/index.md).

package/docs/libraries/janitor.md

@@ -0,0 +1,65 @@
+---
+title: Janitor
+sidebar_position: 3
+---
+
+# Janitor
+
+Cleans connections, instances, promises, and threads. Header: `#include <cluaupp/libs/janitor.hpp>`. Runtime is [howmanysmall/Janitor](https://github.com/howmanysmall/Janitor). Types come from `_impl` — there is no fake `Has` method.
+
+## Create and add
+
+```cpp
+auto* janitor = new Janitor();
+
+janitor->Add(Players->PlayerAdded.Connect(OnPlayer));
+janitor->Add(part, "Destroy");
+janitor->Add(print, true);
+```
+
+| Call | Cleanup |
+| --- | --- |
+| `Add(connection)` | `Disconnect` |
+| `Add(instance)` / `Add(instance, "Destroy")` | `Destroy` |
+| `Add(fn, true)` | call the function |
+| `Add(thread, true)` | `task.cancel` |
+
+## Indexed slots (per player)
+
+The third argument is a namespace. Adding again with the same index removes the previous task first.
+
+```cpp
+janitor->Add(sectionJanitor, "Destroy", player->Name);
+
+if (janitor->Get(player->Name)) {
+	janitor->Remove(player->Name);
+}
+```
+
+`Remove` on a missing index is a no-op. There is **no** `Has` — use `Get`.
+
+## Lifetime
+
+```cpp
+janitor->Cleanup();
+janitor->Destroy();
+janitor->LinkToInstance(player);
+```
+
+- `Cleanup` — run every task, janitor stays usable.
+- `Destroy` — cleanup and freeze the object.
+- `LinkToInstance` — cleanup when that Instance is destroyed.
+
+## Promises
+
+```cpp
+#include <cluaupp/libs/promise.hpp>
+
+janitor->AddPromise(Promise::delay(1));
+```
+
+Cleanup cancels or rejects the promise when the janitor runs.
+
+## Pattern
+
+One janitor for the script. A **child** janitor per player, stored under `player->Name`, removed on `PlayerRemoving`. Copy: [Leaderstats](../examples/leaderstats.md).

package/docs/libraries/more.md

@@ -0,0 +1,79 @@
+---
+title: More libraries
+sidebar_position: 6
+---
+
+# More libraries
+
+Same rule: include the header, call the API. `cluaupp build` already put the Luau in `CluauppLibs`.
+
+## FormatNumber
+
+```cpp
+#include <cluaupp/libs/formatnumber.hpp>
+
+print(FormatNumber::Abbreviate(1500));
+print(FormatNumber::Comma(1500));
+```
+
+## MathUtils
+
+```cpp
+#include <cluaupp/libs/math.hpp>
+
+double t = MathUtils::Lerp(0, 1, 0.5);
+```
+
+## Twinkle (UI)
+
+```cpp
+#include <cluaupp/libs/twinkle.hpp>
+
+Twinkle::Fade(frame, true);
+```
+
+## Module3D
+
+```cpp
+#include <cluaupp/libs/module3d.hpp>
+
+Module3D::Attach3D(viewport, model);
+```
+
+## VfxUtil
+
+```cpp
+#include <cluaupp/libs/vfx.hpp>
+
+VfxUtil::Emit(root);
+VfxUtil::Play(emitter);
+```
+
+## StickyBillboard
+
+```cpp
+#include <cluaupp/libs/stickybillboard.hpp>
+
+auto* billboard = StickyBillboard::new_(adornee, gui);
+billboard->SetText("Hello");
+```
+
+## Fusion / Iris / Cmdr / TopbarPlus / Chrono / EzVisualz / StateMachine / Spring / Display
+
+These are the GitHub systems behind typed `init.luau` borders. Include the matching `<cluaupp/libs/*.hpp>` and call the same names as the upstream README. Cluaupp does not re-document every Fusion `Value` / Cmdr command — use:
+
+| Lib | Header | Upstream |
+| --- | --- | --- |
+| Fusion | `fusion.hpp` | [dphfox/Fusion](https://github.com/dphfox/Fusion) |
+| Iris | `iris.hpp` | [SirMallard/Iris](https://github.com/SirMallard/Iris) |
+| Cmdr | `cmdr.hpp` | [evaera/Cmdr](https://github.com/evaera/Cmdr) |
+| TopbarPlus | `topbarplus.hpp` | [1ForeverHD/TopbarPlus](https://github.com/1ForeverHD/TopbarPlus) |
+| Chrono | `chrono.hpp` | [Parihsz/Chrono](https://github.com/Parihsz/Chrono) |
+| EzVisualz | `ezvisual.hpp` | [arxkdev/ezVisualz](https://github.com/arxkdev/ezVisualz) |
+| StateMachine | `statemachine.hpp` | [Prooheckcp/RobloxStateMachine](https://github.com/Prooheckcp/RobloxStateMachine) |
+| Spring | `spring.hpp` | [nightcycle/spring](https://github.com/nightcycle/spring) |
+| Display | `display.hpp` | [nightcycle/display](https://github.com/nightcycle/display) |
+
+## Types-only
+
+`ArrayIndexer` (`Table<Manifest, "Name">`) and `Occlude` (`Keys<Data, "field">`) are used by generated `{Service}Types.luau`. You rarely include them from game C++.

package/docs/libraries/net.md

@@ -0,0 +1,35 @@
+---
+title: Net
+sidebar_position: 5
+---
+
+# Net
+
+Buffer-packed remotes. Header: `#include <cluaupp/libs/net.hpp>`. Same name on server and client — you do not create `RemoteEvent` instances yourself.
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/net.hpp>
+#include <cluaupp/libs/janitor.hpp>
+
+void OnCoins(Player* player, int amount) {
+	return;
+}
+
+void init() {
+	auto* janitor = new Janitor();
+	auto* coins = Net::Event("Coins");
+	coins->On(OnCoins);
+	janitor->Add(coins);
+}
+```
+
+| Side | API |
+| --- | --- |
+| Server | `Fire(player, ...)`, `FireAll(...)` |
+| Client | `FireServer(...)` |
+| Both | `On(callback)` |
+
+Functions: `Net::Function("Shop")`, then `Invoke` / `InvokeServer`.
+
+Validate everything the client fires. See [safety](../cpp-safety.md). Full copies: [Combat](../examples/combat.md), [Shop](../examples/shop.md).

package/docs/libraries/promise.md

@@ -0,0 +1,27 @@
+---
+title: Promise
+sidebar_position: 4
+---
+
+# Promise
+
+[evaera/roblox-lua-promise](https://github.com/evaera/roblox-lua-promise). Header: `#include <cluaupp/libs/promise.hpp>`.
+
+C++ names `Then` / `Catch` / `Await` / `Cancel` are aliases of `andThen` / `catch` / `await` / `cancel`.
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/promise.hpp>
+
+void AfterWait() {
+	print("1s later");
+}
+
+void init() {
+	Promise::delay(1);
+}
+```
+
+Useful statics: `Promise::delay(seconds)`, `Promise::resolve(value)`, `Promise::reject("err")`.
+
+Cluaupp cannot nest lambdas. Prefer `delay` plus a named callback you already have, or keep promise chains in Luau libraries you call from C++.

package/docs/oop/_category_.json

@@ -0,0 +1,5 @@
+{
+	"label": "OOP structure",
+	"position": 16,
+	"collapsed": false
+}

package/docs/oop/file-tags.md

@@ -0,0 +1,49 @@
+---
+title: File tags
+sidebar_position: 2
+---
+
+# File tags
+
+The **filename** decides the Roblox instance. This is the same key idea as roblox-ts (`*.server.ts` → Script).
+
+| Source | Instance | RunContext |
+| --- | --- | --- |
+| `LeaderstatsServer.server.cpp` | **Script** | **Server** |
+| `DataBoot.client.cpp` | **LocalScript** | Client |
+| `Tools.plugin.cpp` | **Script** | Plugin |
+| `Boot.legacy.cpp` | Script | **Legacy** |
+| `Boot.legacy.server.cpp` | Script | **Legacy** |
+| `Boot.legacy.client.cpp` | LocalScript | Legacy |
+| `Damage.cpp` (no tag) | **ModuleScript** | — |
+
+## Server is not Legacy
+
+`.server.cpp` is **not** `init.server.luau`. Rojo maps `*.server.luau` to a Script with RunContext **Legacy**. Cluaupp emits:
+
+```
+out/server/LeaderstatsServer/
+  init.luau
+  init.meta.json    -- className Script, RunContext Server
+```
+
+`.legacy.server.cpp` is the 1:1 dump that *does* become Legacy.
+
+`.client.cpp` stays `init.client.luau` (LocalScript). Do not add `init.meta.json` on the client boot.
+
+## Where files live
+
+```
+src/server/.../*.server.cpp   → out/server  (ServerScriptService)
+src/client/.../*.client.cpp   → out/client  (StarterPlayerScripts)
+src/shared/.../*.cpp          → out/shared  (ReplicatedStorage)
+```
+
+Name the **system**, not `init.server.cpp`. `LeaderstatsServer.server.cpp` and `DataBoot.server.cpp` are two services.
+
+## Skip the planner
+
+- `"architecture": false` in `cluaupp.config.json`, or
+- `.legacy.server.cpp` / `.legacy.client.cpp` per file
+
+Use legacy only when you want one Luau file with no Main / Controller split.

package/docs/oop/index.md

@@ -0,0 +1,22 @@
+---
+title: OOP structure
+sidebar_position: 1
+---
+
+# OOP structure
+
+The **live site** (not just these markdown files) is GitHub Pages:
+
+- [Learn → OOP structure](https://kartzrbx.github.io/Cluaupp/learn/index.html)
+- [Guide → OOP](https://kartzrbx.github.io/Cluaupp/guide/oop.html)
+- [Examples](https://kartzrbx.github.io/Cluaupp/guide/examples.html)
+
+Cluaupp does **not** compile custom C++ `class` types yet. “OOP” here is how you **lay out systems** so Studio gets services, modules, and lifecycle — the same idea as roblox-ts filename keys + Flamework `@Service`, without decorators.
+
+| Page | What you learn |
+| --- | --- |
+| [File tags](file-tags.md) | `.server` / `.client` / `.plugin` / `.legacy` / untagged |
+| [Services](services.md) | One `.server.cpp` → Main, Controller, Start / Stop |
+| [Modules](modules.md) | Untagged files, structs, named functions as methods |
+
+Planner details: [Architecture](../architecture.md). Folder layout: [Organization](../cpp-organization.md). Full services: [Examples](../examples/index.md).

package/docs/oop/modules.md

@@ -0,0 +1,86 @@
+---
+title: Modules and structs
+sidebar_position: 4
+---
+
+# Modules and structs
+
+Use this when you want a **reusable object** without a tagged Script.
+
+## Untagged `.cpp` = ModuleScript
+
+```
+src/shared/util/Coins.cpp
+```
+
+```cpp
+#include <cluaupp/roblox.hpp>
+
+int DoubleCoins(int coins) {
+	return coins;
+}
+```
+
+```
+out/shared/util/Coins.luau   -- ModuleScript, exported functions
+```
+
+Shared **data and constants** belong in headers (`#include "TemplateData.hpp"`) — they are inlined. Untagged `.cpp` is for a ModuleScript other Luau can `require`. Prefer headers for data and tagged `.server.cpp` / `.client.cpp` for behavior.
+
+## Structs = data, not classes
+
+The subset allows structs for IntelliSense and designated initializers (tables):
+
+```cpp
+struct TemplateData {
+	struct Currencies {
+		int Money = 0;
+		int Level = 1;
+	} Currencies;
+};
+
+TemplateData playerData = TemplateData {};
+```
+
+That is your “class fields”. Methods are **named functions** next to them (`EnsureStat`, `ApplyCurrencies`). Cluaupp does not emit `function TemplateData:GetMoney()`.
+
+## Methods as functions
+
+```cpp
+void EnsureStat(Folder* folder, string name, int value) {
+	auto* stat = folder->FindFirstChild(name);
+	if (stat == nullptr) {
+		cout::print << "EnsureStat: " << name << " not found" << endl;
+		return;
+	}
+}
+```
+
+Pass the instance in (`folder`, `player`). That is composition: the Folder is the object, the function is the method.
+
+## Janitor as the destructor
+
+There is no C++ destructor. Pair “construct” with a Janitor:
+
+```cpp
+auto* janitor = new Janitor();
+janitor->LinkToInstance(player);
+janitor->Add(player->AncestryChanged.Connect(OnAncestry));
+```
+
+When the player leaves, `LinkToInstance` runs `Cleanup`. That is RAII for Roblox.
+
+## Start / Stop
+
+On generated services, `Main.Start` / `Main.Stop` are the constructor / destructor of the **system**. Put connections in Start (or in `init()` / `PlayersManager`). Do not leak `Connect` without a Janitor.
+
+## What not to write
+
+```cpp
+class Shop {
+	int price;
+	void Buy(Player* player);
+};
+```
+
+Custom classes are **not supported**. Split into a struct (fields) + functions (methods) + a `.server.cpp` or untagged module (lifetime).

package/docs/oop/services.md

@@ -0,0 +1,83 @@
+---
+title: Services
+sidebar_position: 3
+---
+
+# Services
+
+Write **one tagged file per system**. Cluaupp reads the AST and emits a PascalCase folder: `Main`, managers, controllers, `*Types`.
+
+## Example: leaderstats
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+
+void EnsureStat(Folder* folder, string name, int value) {
+	return;
+}
+
+void ApplyCurrencies(Player* player, Data* data) {
+	return;
+}
+
+void OnCurrenciesChanged() {
+	return;
+}
+
+void SetupPlayerManager(Player* player) {
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		return;
+	}
+	ApplyCurrencies(player, data);
+	data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged);
+}
+
+void init() {
+	auto* players = GetService<Players>();
+	players->PlayerAdded.Connect(SetupPlayerManager);
+}
+```
+
+Typical output:
+
+```
+out/server/LeaderstatsServer/
+  init.luau              -- Script, RunContext Server
+  init.meta.json
+  Main.luau              -- Start / Stop
+  PlayersManager.luau    -- PlayerAdded + Janitor
+  DataController.luau    -- your WaitFor / GetChangedSignal
+  CacheController.luau   -- if you create IntValue folders
+  LeaderstatsServerTypes.luau
+```
+
+Your functions stay in the matching controller. The planner does not drop `SetupPlayerManager` because `init` still calls it.
+
+## Lifecycle
+
+Generated `Main` exposes `Start` / `Stop`. Managers own a Janitor. `Stop` cleans connections.
+
+You do not write `class LeaderstatsServer` — name the **file** `LeaderstatsServer.server.cpp` and keep **functions** as the public API.
+
+## Boot vs gameplay
+
+Keep DataService `Init` in `DataBoot.server.cpp` / `DataBoot.client.cpp`. Keep leaderstats / combat in their own `.server.cpp`. Services `WaitFor` after boot has run.
+
+## What becomes which role
+
+| Your C++ | Generated role |
+| --- | --- |
+| `PlayerAdded`, `GetPlayers` | `PlayersManager` |
+| `Folder` + `IntValue` | `CacheController` |
+| `DataService`, `GetChangedSignal` | `DataController` |
+| `TakeDamage`, `Humanoid` | `CombatController` |
+| `Net::Event` | `NetController` |
+| `UserInputService` | `InputController` |
+| wiring | `Main.Start` / `Main.Stop` |
+
+A tiny `print` in `init.client.cpp` stays a single LocalScript. The planner does not invent Managers for hello-world.
+
+Copy-paste: [Examples](../examples/index.md).

package/docs/print-cout.md

@@ -0,0 +1,91 @@
+---
+title: print and cout
+sidebar_position: 8
+---
+
+# print and cout
+
+Cluaupp has no `<iostream>`. Logging is Roblox `print` / `warn` / `error`. You can still write C++-style `cout` / `cerr` / `endl` — the compiler flattens them.
+
+## Globals
+
+```cpp
+print("ok");
+warn("careful");
+error("fail");
+```
+
+```luau
+print("ok")
+warn("careful")
+error("fail")
+```
+
+`print` in C++ takes a string (and chained `cout` pieces). Do not expect full C++ `std::cout` overloads.
+
+## Stream: `cout << … << endl`
+
+Each `<<` is another argument. `endl` ends the statement (no extra `"\n"`).
+
+```cpp
+cout << "EnsureStat: " << name << " not found" << endl;
+```
+
+```luau
+print("EnsureStat: ", name, " not found")
+```
+
+`cerr` is the same chain, emitted as `warn`:
+
+```cpp
+cerr << "failed to load " << player->Name << endl;
+```
+
+```luau
+warn("failed to load ", player.Name)
+```
+
+## Levels: `cout::print` / `warn` / `error` / `ping`
+
+Use `::` to pick the Roblox function. The stream still concatenates with `<<`.
+
+```cpp
+cout::print << "EnsureStat test: " << name << " not found" << endl;
+cout::warn << "missing folder for " << player->Name << endl;
+cout::error << "profile failed" << endl;
+cout::ping << "here" << endl;
+```
+
+```luau
+print("EnsureStat test: ", name, " not found")
+warn("missing folder for ", player.Name)
+error("profile failed")
+print("here")
+```
+
+| C++ | Luau |
+| --- | --- |
+| `cout << … << endl` | `print(…)` |
+| `cout::print << … << endl` | `print(…)` |
+| `cout::warn << … << endl` | `warn(…)` |
+| `cout::error << … << endl` | `error(…)` |
+| `cout::ping << … << endl` | `print(…)` |
+| `cerr << … << endl` | `warn(…)` |
+
+`cout::ping` is a debug alias of `print` (no extra Studio highlight).
+
+## Call form (no `<<`)
+
+```cpp
+cout::print("ok");
+cout::warn("careful");
+cout::error("fail");
+cout::ping("here");
+cout::endl();
+```
+
+`cout::endl()` is a no-op in Luau (flush is already the statement). Prefer `<< endl` on a stream.
+
+## IntelliSense
+
+`struct cout` / `cerr` and `endl` live in `<cluaupp/roblox.hpp>`. Include that header so clangd knows `cout::print` and `operator<<`.