cluaupp 0.2.2 → 1.0.0

package/docs/examples/combat.md

@@ -3,237 +3,29 @@ title: Combat (server validation)
 sidebar_position: 4
 ---
 
-# Combat (server validation)
+# Combat
 
-The client never sends **damage**. It sends **who I want to hit**. The server decides range, cooldown, alive state, and the damage constant.
+Live source: [`examples/game/src/server/combat.server.clpp`](../../examples/game/src/server/combat.server.clpp). Language: [CL++](https://kartzrbx.github.io/CLPP/).
 
-Pair with [Data boot](data-boot.md) if a kill should grant Money.
+This sample uses exclusive CL++:
 
-## Shared config
+- `guard` / `match` instead of nested null checks
+- `signal<Player*, int> OnHit` and `OnHit~>Connect` / `OnHit::Fire`
+- `observable int combo`
+- `[[server]]` on `WatchWorkspace`
+- `spawn { task::wait(1); … }`
 
-`src/shared/constants/CombatConfig.hpp`
+The client never decides damage. Touched parts fire `OnHit`; the server prints combo and destroys the part.
 
-```cpp
-#pragma once
+```clpp
+#include <clpp/roblox.clh>
+#include <clpp/libs/janitor.clh>
 
-const double ATTACK_RANGE = 12;
-const double ATTACK_COOLDOWN = 0.4;
-const int ATTACK_DAMAGE = 12;
-const int KILL_REWARD = 5;
+struct CombatServer {
+	Janitor* janitor;
+	signal<Player*, int> OnHit;
+	void PlayerEntered(Player* player);
+	void BindPart(BasePart* part);
+	void WatchWorkspace();
+};
 ```
-
-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/hud.md

@@ -5,92 +5,24 @@ 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.
+Live source: [`examples/game/src/client/hud.client.clpp`](../../examples/game/src/client/hud.client.clpp). Fusion API: [CL++](https://kartzrbx.github.io/CLPP/).
 
-Put a ScreenGui named `Hud` in StarterGui with `MoneyLabel` and `LevelLabel` (`TextLabel`).
+Client-only (`[[client]]`). `Fusion:scoped` / `Fusion:Value` / `Fusion:Computed` / `Fusion:New` build a coins label. `guard` fails if `LocalPlayer` is missing.
 
-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);
-}
+```clpp
+#include <clpp/roblox.clh>
+#include <clpp/libs/fusion.clh>
 
+[[client]]
 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;
+	Players* players = GetService<Players>();
+	Player* localPlayer = players.LocalPlayer;
+	guard (localPlayer != null) else {
+		report("LocalPlayer missing");
 		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));
+	auto scope = Fusion:scoped();
+	auto coins = Fusion:Value(scope, 0);
+	coins(100);
 }
 ```
-
-## 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

@@ -5,28 +5,21 @@ 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.
+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/).
 
-In this repo the live sample is [`examples/game`](../../examples/game) (`src/server`, `src/client`, `src/shared`). Compiler TypeScript is never mixed with game C++. `cluaupp init` still copies [`templates/game`](../../templates/game).
-
-These are **not** dumps of `int main()`. Entry is `void init()`. There are no lambdas and no custom C++ classes — named functions + structs.
+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/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
+  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.

package/docs/examples/leaderstats.md

@@ -5,136 +5,65 @@ 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.
+Canonical copy (three files): [Docs → Example: Leaderstats](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
 
-It does **not** call `DataService.Init`. Boot that in [Data boot](data-boot.md).
+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.
 
-## Why this shape
+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 |
 | --- | --- |
-| 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) |
+| 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. |
 
-## `LeaderstatsServer.server.cpp`
+## Header
 
 ```cpp
+#pragma once
 #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);
-}
+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);
+};
+```
 
-void OnPlayerRemoving(Player* player) {
-	if (janitor->Get(player->Name)) {
-		janitor->Remove(player->Name);
-	}
-}
+## `PlayerEntered`
 
-void OnClose() {
-	janitor->Destroy();
-}
-
-void init() {
-	for (Player* player : Players->GetPlayers()) {
-		SetupPlayer(player);
+```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(Players->PlayerAdded.Connect(SetupPlayer));
-	janitor->Add(Players->PlayerRemoving.Connect(OnPlayerRemoving));
-	game->BindToClose(OnClose);
+	janitor->Add(leaderstatsFolder, "Destroy", GetPlayerJanitorKey(player));
 }
 ```
 
-## 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).
+`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).