cluaupp 0.1.2 → 0.1.5

package/docs/examples/combat.md

@@ -0,0 +1,239 @@
+---
+title: Combat (server validation)
+sidebar_position: 4
+---
+
+# Combat (server validation)
+
+The client never sends **damage**. It sends **who I want to hit**. The server decides range, cooldown, alive state, and the damage constant.
+
+Pair with [Data boot](data-boot.md) if a kill should grant Money.
+
+## Shared config
+
+`src/shared/constants/CombatConfig.hpp`
+
+```cpp
+#pragma once
+
+const double ATTACK_RANGE = 12;
+const double ATTACK_COOLDOWN = 0.4;
+const int ATTACK_DAMAGE = 12;
+const int KILL_REWARD = 5;
+```
+
+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/data-boot.md

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

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