cluaupp 1.0.0 → 1.3.0

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).

package/docs/libraries/index.md

@@ -1,23 +0,0 @@
----
-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 |
-| [Declarative UI](ui.md) | Fusion, Iris, Vide, React/Roact — no JSX |
-| [More libraries](more.md) | FormatNumber, Twinkle, TopbarPlus, EzVisualz, … |
-
-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

@@ -1,65 +0,0 @@
----
-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

@@ -1,81 +0,0 @@
----
-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
-
-Cluaupp has **no JSX**. Declarative UI is function calls. First-party: Fusion (reactive) and Iris (immediate-mode debug). Vide and Roact/React use the same C++ spelling (`createElement` / `source`), not `<frame />`. Handbook: [Declarative UI](https://kartzrbx.github.io/Cluaupp/docs/ui.html).
-
-Include the matching `<cluaupp/libs/*.hpp>` and call the same names as the upstream README:
-
-| 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

@@ -1,35 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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/libraries/ui.md

@@ -1,76 +0,0 @@
----
-title: Declarative UI
-sidebar_position: 5
----
-
-# Declarative UI
-
-Live handbook (examples, C++ / Luau tabs): **[Declarative UI](https://kartzrbx.github.io/Cluaupp/docs/ui.html)**.
-
-roblox-ts can compile [Roact JSX](https://roblox-ts.com/docs/guides/roact-jsx) because TypeScript has JSX. **Cluaupp does not.** There are no `<frame />` tags. You call the library the way Luau does: functions, designated-initializer tables, lambdas.
-
-## Pick a model
-
-| When you want… | Use | In Cluaupp |
-| --- | --- | --- |
-| A few labels you set by hand | Imperative Instances | `new TextLabel(gui)` |
-| UI that follows state | [Fusion](https://github.com/dphfox/Fusion) | Shipped: `#include <cluaupp/libs/fusion.hpp>` |
-| The same idea, sources | [Vide](https://github.com/centau/vide) | Not shipped — calling convention on the handbook |
-| A virtual tree | Roact / [jsdotlua React](https://github.com/jsdotlua/react) | Not shipped — `createElement`, never JSX |
-| Studio debug panels | [Iris](https://github.com/SirMallard/Iris) | Shipped: `#include <cluaupp/libs/iris.hpp>` |
-| Topbar / fade / rainbow | TopbarPlus, Twinkle, EzVisualz | Shipped — polish Instances you already have |
-
-Fusion and Iris are in CluauppLibs. Vide and React/Roact are **not** vendored.
-
-## JSX → Cluaupp
-
-| roblox-ts JSX | Cluaupp |
-| --- | --- |
-| `<frame Size={u} />` | `React::createElement("Frame", { .Size = u })` |
-| `<textlabel Key="Coins" />` | `.Key = "Coins"` on the props table |
-| `Event={{ Activated: fn }}` | `.Event = { .Activated = fn }` |
-| `<MyButton text="Buy" />` | `React::createElement(MyButton, { .text = "Buy" })` |
-
-## Fusion (shipped)
-
-```cpp
-#include <cluaupp/libs/fusion.hpp>
-
-FusionScope scope = Fusion::scoped();
-FusionState coins = Fusion::Value(0);
-Fusion::New("TextLabel")({
-	.Name = "Coins",
-	.Parent = gui,
-	.Size = UDim2::fromScale(1, 0.1),
-});
-```
-
-Wire `coins(newValue)` from `DataService::Client` `GetChangedSignal(Paths.Currencies.Coins)`. Use `Computed` for strings, `Hydrate` for a ScreenGui that already exists in Studio, `Spring` / `Tween` for motion.
-
-## Vide / React
-
-Same subset: **no JSX**. Vide is `source` / `derive` / `create("TextLabel")({ .Parent = gui })`. React is `createElement("Frame", { .Key = "Child" }, child)` plus `Key`, `Ref`, `Change`, `Event` as table fields. Full copies with C++ / Luau tabs: the [handbook page](https://kartzrbx.github.io/Cluaupp/docs/ui.html).
-
-## Iris (shipped, debug only)
-
-```cpp
-#include <cluaupp/libs/iris.hpp>
-
-void DrawEconomy() {
-	if (Iris::Window("Economy")) {
-		Iris::Text("Coins");
-		Iris::End();
-	}
-}
-
-void init() {
-	Iris::Init();
-	Iris::Connect(DrawEconomy);
-}
-```
-
-Do not use Iris as the live player HUD. Pair every `Window` / `Tree` with `End()`.
-
-## One owner per ScreenGui
-
-Do not mount Fusion and React on the same gui. Twinkle / TopbarPlus / EzVisualz can decorate that owner’s Instances. Client code must not `Set` persisted DataService paths.

package/docs/migration.md

@@ -1,38 +0,0 @@
-# Migrate C++ games to CL++
-
-Cluaupp 1.0 compiles **CL++**, not a C++ subset. Language docs: [kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/).
-
-## Files
-
-| Before | After |
-| --- | --- |
-| `*.server.cpp` | `*.server.clpp` |
-| `*.client.cpp` | `*.client.clpp` |
-| untagged `*.cpp` | `*.clp` |
-| `*.h` / `*.hpp` | `*.clh` |
-
-`#include <cluaupp/roblox.hpp>` → `#include <clpp/roblox.clh>`  
-`#include <cluaupp/libs/janitor.hpp>` → `#include <clpp/libs/janitor.clh>`  
-Quoted includes: `"leaderstats.h"` → `"leaderstats.clh"`.
-
-## Operators and IO
-
-| Old C++ subset | CL++ | Luau |
-| --- | --- | --- |
-| `player->Name` | `player.Name` | `.` |
-| `player->GetPlayers()` | `player::GetPlayers()` | `:` |
-| `DataService::Server` | `DataService:Server` | `.` |
-| `"hi " + name` | `"hi " .: name` | `..` |
-| `signal.Connect(fn)` | `signal~>Connect(fn)` | Janitor `Add` |
-| `print` / `error` | `post` / `report` | `print` / `error` |
-| `nullptr` | `null` | `nil` |
-| `[](Player* p) { }` | `func [](Player* p) { }` | `function` |
-
-## Workflow
-
-1. Install CL++: [github.com/KartzRbx/CLPP](https://github.com/KartzRbx/CLPP) (`cargo install --path .`).
-2. `clpp install` (editor highlighting + IntelliSense).
-3. Rename sources and apply the table above.
-4. `cluaupp build` — `clpp` must be on PATH (`CLPP_PATH` if needed).
-
-`"architecture": true` (ForeverHD folders) is not generated in 1.0. One source file still becomes one `.luau` file.

package/docs/oop/_category_.json

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

package/docs/oop/file-tags.md

@@ -1,24 +0,0 @@
----
-title: File tags
-sidebar_position: 2
----
-
-# File tags
-
-The **filename** decides the Roblox instance (same idea as roblox-ts).
-
-| Source | Instance |
-| --- | --- |
-| `LeaderstatsServer.server.clpp` | Script |
-| `Hud.client.clpp` | LocalScript |
-| `Tools.plugin.clpp` | Plugin Script |
-| `damage.clp` (no tag) | ModuleScript |
-| `PlayerData.clh` | ModuleScript |
-
-```
-src/server/boot/DataBoot.server.clpp  →  out/server/boot/DataBoot.server.luau
-src/client/hud.client.clpp            →  out/client/hud.client.luau
-src/shared/config.clp                 →  out/shared/config.luau
-```
-
-Language details: [CL++ docs](https://kartzrbx.github.io/CLPP/).

package/docs/oop/index.md

@@ -1,29 +0,0 @@
----
-title: OOP structure
-sidebar_position: 1
----
-
-# Structs and methods
-
-Language details: [CL++](https://kartzrbx.github.io/CLPP/). Filename tags decide Script / LocalScript / ModuleScript.
-
-Declare the type in a `.clh`, implement `Class::Method` in a `.clp` / `.clpp`. Capture one service table in `void init()`.
-
-```clpp
-#pragma once
-#include <clpp/roblox.clh>
-#include <clpp/libs/janitor.clh>
-
-struct LeaderstatsServer {
-	static constexpr int STARTING_COINS = 0;
-	Janitor* janitor;
-	string GetPlayerJanitorKey(Player* player);
-	void PlayerEntered(Player* player);
-};
-```
-
-| Page | What you learn |
-| --- | --- |
-| [File tags](file-tags.md) | `.server.clpp` / `.client.clpp` / `.clh` |
-| [Services](services.md) | `init()` singletons |
-| [Modules](modules.md) | shared `.clp` |