cluaupp 0.1.2 → 0.1.4

package/docs/examples/hud.md

@@ -0,0 +1,96 @@
+---
+title: HUD
+sidebar_position: 6
+---
+
+# HUD
+
+Client-only: wait for the replicated profile, write labels, listen for currency changes. No `Set` on persisted paths from the client.
+
+Put a ScreenGui named `Hud` in StarterGui with `MoneyLabel` and `LevelLabel` (`TextLabel`).
+
+Define callbacks **above** `init()` so clangd and the subset both see them (no lambdas).
+
+## `HudClient.client.cpp`
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+#include <cluaupp/libs/formatnumber.hpp>
+#include <cluaupp/libs/twinkle.hpp>
+
+Players* Players = GetService<Players>();
+Janitor* janitor = new Janitor();
+
+TextLabel* FindLabel(PlayerGui* playerGui, string name) {
+	if (playerGui == nullptr) {
+		return nullptr;
+	}
+	Instance* gui = playerGui->FindFirstChild("Hud");
+	if (gui == nullptr) {
+		return nullptr;
+	}
+	return gui->FindFirstChild(name);
+}
+
+void Render(Data* data, TextLabel* moneyLabel, TextLabel* levelLabel) {
+	if (data == nullptr) {
+		return;
+	}
+	int money = data->Get(DataService::Client.Paths.Currencies.Money);
+	int level = data->Get(DataService::Client.Paths.Currencies.Level);
+	if (moneyLabel != nullptr) {
+		moneyLabel->Text = FormatNumber::Abbreviate(money);
+	}
+	if (levelLabel != nullptr) {
+		levelLabel->Text = FormatNumber::Comma(level);
+	}
+}
+
+void OnCurrenciesChanged() {
+	Player* player = Players->LocalPlayer;
+	if (player == nullptr) {
+		return;
+	}
+	PlayerGui* playerGui = player->FindFirstChildOfClass("PlayerGui");
+	TextLabel* moneyLabel = FindLabel(playerGui, "MoneyLabel");
+	TextLabel* levelLabel = FindLabel(playerGui, "LevelLabel");
+	Render(DataService::Client.Get(), moneyLabel, levelLabel);
+}
+
+void init() {
+	Player* player = Players->LocalPlayer;
+	if (player == nullptr) {
+		return;
+	}
+	PlayerGui* playerGui = player->FindFirstChildOfClass("PlayerGui");
+	if (playerGui == nullptr) {
+		return;
+	}
+
+	Data* data = DataService::Client.WaitForData();
+	if (data == nullptr) {
+		cout::warn << "HUD: profile missing" << endl;
+		return;
+	}
+
+	TextLabel* moneyLabel = FindLabel(playerGui, "MoneyLabel");
+	TextLabel* levelLabel = FindLabel(playerGui, "LevelLabel");
+	Render(data, moneyLabel, levelLabel);
+
+	if (moneyLabel != nullptr) {
+		Twinkle::Fade(moneyLabel, true);
+	}
+
+	janitor->Add(data->GetChangedSignal(DataService::Client.Paths.Currencies).Connect(OnCurrenciesChanged));
+}
+```
+
+## Rules
+
+- Call `DataService::Client.Init()` in [Data boot](data-boot.md) first. Script order in StarterPlayerScripts is not a contract — `WaitForData` yields until the profile exists.
+- Do not `data->Set` Money from the HUD. Display only.
+- `Twinkle::Fade` is optional. See [more libraries](../libraries/more.md).
+
+`HudClient.client.cpp` is a LocalScript (`init.client.luau`).

package/docs/examples/index.md

@@ -0,0 +1,43 @@
+---
+title: Examples
+sidebar_position: 1
+---
+
+# Examples
+
+High-quality Cluaupp systems you can copy. Each page is a full service: C++ that the subset actually compiles, server authority, Janitor cleanup, and the file names Studio expects.
+
+These are **not** dumps of `int main()`. Entry is `void init()`. There are no lambdas and no custom C++ classes — named functions + structs.
+
+## Suggested layout
+
+```
+src/
+  shared/constants/TemplateData.hpp
+  shared/constants/CombatConfig.hpp
+  shared/constants/ShopCatalog.hpp
+  server/boot/DataBoot.server.cpp
+  client/boot/DataBoot.client.cpp
+  server/services/leaderstats/LeaderstatsServer.server.cpp
+  server/services/combat/CombatServer.server.cpp
+  client/controllers/combat/CombatClient.client.cpp
+  server/services/shop/ShopServer.server.cpp
+  client/controllers/shop/ShopClient.client.cpp
+  client/controllers/hud/HudClient.client.cpp
+  server/services/weapons/SwordServer.server.cpp
+```
+
+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

@@ -0,0 +1,140 @@
+---
+title: Leaderstats
+sidebar_position: 3
+---
+
+# Leaderstats
+
+Roblox shows the player list from a Folder named exactly `leaderstats` under the Player, with `IntValue` / `StringValue` children. This service **creates** those values, then mirrors DataService currencies into them.
+
+It does **not** call `DataService.Init`. Boot that in [Data boot](data-boot.md).
+
+## Why this shape
+
+| Rule | Why |
+| --- | --- |
+| Create the Folder if missing | `FindFirstChild` is not a constructor |
+| Create the stat if missing | Returning early when it is absent never shows Money |
+| `StringValue` + `FormatNumber::Abbreviate` | Player list wants a string like `1.5K` |
+| Janitor per player, keyed by `player->Name` | Leaving the game must `Destroy` the section janitor |
+| `GetChangedSignal(Paths.Currencies)` | HUD / list update without polling |
+| Named function, not a lambda | Cluaupp has no lambdas. The shared callback refreshes **all** players (currency writes are rare) |
+
+## `LeaderstatsServer.server.cpp`
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+#include <cluaupp/libs/formatnumber.hpp>
+
+Players* Players = GetService<Players>();
+Janitor* janitor = new Janitor();
+
+void EnsureStat(Folder* leaderstats, string name) {
+	Instance* existing = leaderstats->FindFirstChild(name);
+	if (existing != nullptr) {
+		return;
+	}
+	StringValue* stat = new StringValue(leaderstats);
+	stat->Name = name;
+	stat->Value = "0";
+}
+
+void SetStat(Folder* leaderstats, string name, int value) {
+	StringValue* stat = leaderstats->FindFirstChild(name);
+	if (stat == nullptr) {
+		cout::warn << "leaderstats missing " << name << endl;
+		return;
+	}
+	stat->Value = FormatNumber::Abbreviate(value);
+}
+
+Folder* EnsureLeaderstats(Player* player) {
+	Folder* leaderstats = player->FindFirstChild("leaderstats");
+	if (leaderstats != nullptr) {
+		return leaderstats;
+	}
+	leaderstats = new Folder(player);
+	leaderstats->Name = "leaderstats";
+	return leaderstats;
+}
+
+void ApplyCurrencies(Player* player) {
+	Data* data = DataService::Server.Get(player);
+	if (data == nullptr) {
+		return;
+	}
+	Folder* leaderstats = player->FindFirstChild("leaderstats");
+	if (leaderstats == nullptr) {
+		return;
+	}
+	int money = data->Get(DataService::Server.Paths.Currencies.Money);
+	int level = data->Get(DataService::Server.Paths.Currencies.Level);
+	SetStat(leaderstats, "Money", money);
+	SetStat(leaderstats, "Level", level);
+}
+
+void OnCurrenciesChanged() {
+	for (Player* player : Players->GetPlayers()) {
+		ApplyCurrencies(player);
+	}
+}
+
+void SetupPlayer(Player* player) {
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		cout::warn << "no profile for " << player->Name << endl;
+		return;
+	}
+
+	Folder* leaderstats = EnsureLeaderstats(player);
+	EnsureStat(leaderstats, "Money");
+	EnsureStat(leaderstats, "Level");
+	ApplyCurrencies(player);
+
+	Janitor* section = new Janitor();
+	section->Add(data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged));
+	section->Add(leaderstats, "Destroy");
+	janitor->Add(section, "Destroy", player->Name);
+}
+
+void OnPlayerRemoving(Player* player) {
+	if (janitor->Get(player->Name)) {
+		janitor->Remove(player->Name);
+	}
+}
+
+void OnClose() {
+	janitor->Destroy();
+}
+
+void init() {
+	for (Player* player : Players->GetPlayers()) {
+		SetupPlayer(player);
+	}
+	janitor->Add(Players->PlayerAdded.Connect(SetupPlayer));
+	janitor->Add(Players->PlayerRemoving.Connect(OnPlayerRemoving));
+	game->BindToClose(OnClose);
+}
+```
+
+## Output
+
+`LeaderstatsServer.server.cpp` becomes a service folder: `init.luau` (Script, RunContext **Server**), `Main`, `PlayersManager`, `DataController` / `CacheController`, Types. Your functions stay in the domain controller. See [services](../oop/services.md).
+
+## Bugs this example avoids
+
+| Broken | Correct |
+| --- | --- |
+| `if (!existing) { return; }` then never create the value | `EnsureStat` **creates** when missing |
+| `if (!money) { money->Value = ... }` | That writes only when the child is **nil** (crash / no-op). Set when the child **exists** |
+| `DataService.Get` before `WaitFor` on join | `WaitFor` in `SetupPlayer`, `Get` in the refresh path |
+| `int main()` | `void init()` |
+| One global connection, never removed | Section janitor destroyed on `PlayerRemoving` |
+
+`Paths.Currencies` is valid **after** your Template was passed to `Init`. The library header does not define those fields.
+
+## IntValue vs StringValue
+
+Use `IntValue` if you want the default numeric sort and no abbreviation. Use `StringValue` + `FormatNumber::Abbreviate` for `1.5K`. Do not mix both names (`Money` twice).

package/docs/examples/shop.md

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

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

@@ -122,13 +122,15 @@ If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau
 
 ## IntelliSense
 
-`cluaupp init` copies `include/cluaupp/roblox.hpp`, `.vscode/c_cpp_properties.json`, and `compile_flags.txt` (clangd). `cluaupp build` refreshes `include/cluaupp/` so completions stay in sync with the compiler.
+`cluaupp init` writes the C++ IntelliSense config and installs Microsoft `ms-vscode.cpptools` (via VSIX on Cursor). Then reload the window.
 
-In this repo the include path is `cluau/include` (and `game/include`). After opening a `.cpp` file, complete `Player`, `FindFirstChild`, `GetPlayers`, and `Vector3`.
+```bash
+cluaupp intellisense
+```
 
-The header is **not** compiled to Luau; it only feeds the C++ language server. Use `#include <cluaupp/roblox.hpp>` at the top of each source file.
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau.
 
-Reload the window (Command Palette → **Developer: Reload Window**) if completions were missing before the include path existed.
+See [IntelliSense](intellisense.md).
 
 ## Watch
 
@@ -153,17 +155,21 @@ void init() {
 }
 ```
 
-Wally is optional. Fusion, Cmdr, DataServiceV2, and the rest ship **inside** `libs/` (full GitHub source). See [Libraries](libraries.md).
+Wally is optional. Fusion, Cmdr, DataServiceV2, and the rest ship **inside** `libs/` (full GitHub source). See [Libraries](libraries/index.md) — start with [DataService Init](libraries/dataservice.md) and [Janitor](libraries/janitor.md).
 
-See [Libraries](libraries.md), [types](cpp-types.md), [safety](cpp-safety.md).
+See [Libraries](libraries/index.md), [OOP](oop/index.md), [types](cpp-types.md), [safety](cpp-safety.md).
 
 ## Next
 
 - [C++ → Luau syntax](syntax.md)
+- [print and cout](print-cout.md)
 - [C++ types](cpp-types.md)
 - [const](cpp-const.md)
 - [Safety](cpp-safety.md)
 - [Organization](cpp-organization.md)
 - [Architecture](architecture.md)
+- [OOP structure](oop/index.md)
+- [Libraries](libraries/index.md)
+- [Examples](examples/index.md)
 - [Roblox API](roblox-api.md)
 - [CLI](cli.md)

package/docs/intellisense.md

@@ -0,0 +1,31 @@
+# IntelliSense
+
+`cluaupp init` and `cluaupp intellisense` install the same setup that works in Cursor:
+
+1. Microsoft [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) (`ms-vscode.cpptools`)
+2. `.vscode/c_cpp_properties.json` — LLVM `clang++`, C++20, `include/` + `src/`, `compile_commands.json`
+3. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete
+4. The Cluaupp completion engine (Roblox APIs + your `struct`s)
+
+Cursor’s marketplace does not list `ms-vscode.cpptools`. Cluaupp downloads the official VSIX from [vscode-cpptools releases](https://github.com/microsoft/vscode-cpptools/releases) and runs `cursor --install-extension`.
+
+## Install
+
+```bash
+cluaupp intellisense
+```
+
+Reload: Command Palette → **Developer: Reload Window**. Status bar `{} C++` should read **IntelliSense: Ready**.
+
+`cluaupp build` / `watch` only refresh `compile_commands.json` (no download). They never keep deleted files in the compilation database.
+
+## Config that ships
+
+| File | Role |
+| --- | --- |
+| `.vscode/c_cpp_properties.json` | compiler path, include path, `compileCommands` |
+| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: default`, `clangd.enable: false` |
+| `.vscode/extensions.json` | recommends `ms-vscode.cpptools` |
+| `compile_commands.json` | one entry per `src/` file |
+
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is not compiled to Luau.

package/docs/intro.md

@@ -7,7 +7,7 @@ sidebar_position: 1
 
 **The definitive merge of C++ and modern Luau.** You write a C++ subset. Cluaupp emits [Luau](https://luau.org/getting-started) with `--!strict`, `local`, and `const`, and calls the Roblox API the way Studio does.
 
-This site is built with [Moonwave](https://eryn.io/moonwave/) for local markdown docs (`npm run docs`). The public site is the cinematic engine dump at [GitHub Pages](https://kartzrbx.github.io/Cluaupp/). The language is in the same spirit as [roblox-ts](https://roblox-ts.com): a familiar syntax, a restricted subset, readable output.
+This site is built with [Moonwave](https://eryn.io/moonwave/) for local markdown (`npm run docs`). The **public** site is generated into `site/` and deployed to [GitHub Pages](https://kartzrbx.github.io/Cluaupp/) (Learn tabs, OOP, Examples, API). The language is in the same spirit as [roblox-ts](https://roblox-ts.com): a familiar syntax, a restricted subset, readable output.
 
 ## What you get
 
@@ -34,4 +34,4 @@ void init() {
 }
 ```
 
-Read [Getting started](getting-started.md), then [C++ types](cpp-types.md) and [Libraries](libraries.md).
+Read [Getting started](getting-started.md), then [Examples](examples/index.md), [Libraries](libraries/index.md), and [OOP structure](oop/index.md).

package/docs/libraries/_category_.json

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