cluaupp 1.0.0 → 1.3.0

package/docs/cpp-organization.md

@@ -1,63 +0,0 @@
----
-title: Organization
-sidebar_position: 13
----
-
-# Organization
-
-A Cluaupp game is laid out like a roblox-ts project on disk. One tagged `.cpp` becomes one Luau instance (`leaderstats.server.luau`, `hud.client.luau`). See [Architecture](architecture.md).
-
-```
-src/
-  server/     → Script (out/server)
-  client/     → LocalScript (out/client)
-  shared/     → ModuleScript (out/shared)
-include/cluaupp/   IntelliSense
-libs/              CluauppLibs (full Janitor, Fusion, Cmdr, DataService, …)
-Packages/          extra Wally packages only
-cluaupp.config.json
-default.project.json
-wally.toml
-```
-
-## Server / client / shared
-
-| Folder | Runs on | Allowed to |
-| --- | --- | --- |
-| `src/server` | Server | DataStore, DataService writes, `Net:Fire` |
-| `src/client` | Client | UI, Module3D, Twinkle, camera, `Net:FireServer` |
-| `src/shared` | Both | types, `const` config, FormatNumber, MathUtils |
-
-If a file needs `DataStoreService`, it is server. If it needs `UserInputService`, it is client. Shared code must compile in both.
-
-## Headers vs scripts
-
-- `.h` / `.hpp` in `src/` are inlined (`#include "config.h"`) and can hold `const` values and prototypes.
-- `#include <cluaupp/...>` is IntelliSense only — never inlined. `cluaupp build` copies those headers into the game `include/` folder. Cursor/clangd also reads `compile_flags.txt`.
-
-Keep config in `src/shared/config.h`:
-
-```cpp
-#pragma once
-const int STARTING_COINS = 0;
-const string REMOTE_COINS = "Coins";
-```
-
-## One module, one job
-
-`leaderstats.server.cpp` creates leaderstats. It does not also open the shop UI. Name files after the system: `inventory.server.cpp`, `shop.client.cpp`.
-
-`*.server.cpp` / `*.client.cpp` are **tags** (the same keys roblox-ts uses). Untagged `.cpp` is a ModuleScript. Set `"architecture": true` only if you want the old PascalCase folder split. See [Architecture](architecture.md) and [OOP structure](oop/index.md).
-
-## CluauppLibs vs extra Wally
-
-| Need | Where |
-| --- | --- |
-| Janitor, Promise, Fusion, Iris, Cmdr, TopbarPlus, Chrono, DataServiceV2, EzVisualz, StateMachine, Spring, Display, Module3D, FormatNumber, Net, MathUtils, Twinkle | `CluauppLibs` (copied on `cluaupp build` from GitHub-vendored `runtime/`) |
-| Some other community package | `wally.toml` → `Packages` |
-
-Do not install a second Janitor from Wally unless you have a reason — CluauppLibs already has howmanysmall/Janitor. DataServiceV2 still bundles its own janitor/quicknet/signal inside the DataService folder.
-
-How-tos: [Libraries](libraries/index.md). Service layout: [OOP](oop/index.md). Copy-paste: [Examples](examples/index.md).
-
-Next: [advanced Cluaupp](cpp-advanced.md).

package/docs/cpp-safety.md

@@ -1,62 +0,0 @@
----
-title: Safety
-sidebar_position: 12
----
-
-# Safety
-
-Safety in Cluaupp is not a sandbox flag. It is a set of habits the compiler and libraries make cheap.
-
-## 1. Never trust the client
-
-[Net](libraries/net.md) lets a client `FireServer`. The server must validate:
-
-```cpp
-void OnBuy(Player* player, int productId) {
-	if (productId < 1) {
-		return;
-	}
-	int price = PriceOf(productId);
-	Data* data = DataService::Server.WaitFor(player);
-	if (data == nullptr) {
-		return;
-	}
-	int coins = data->Get(DataService::Server.Paths.Currencies.Money);
-	if (coins < price) {
-		return;
-	}
-	data->Set(DataService::Server.Paths.Currencies.Money, coins - price);
-}
-```
-
-Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`). Full systems: [Shop](examples/shop.md), [Combat](examples/combat.md).
-
-## 2. Clean up with Janitor
-
-Every `Connect` that outlives a player, a GUI, or a tool needs a [Janitor](libraries/janitor.md). Leaving a step, destroying a character, or closing a menu should `Cleanup()` or `LinkToInstance`.
-
-```cpp
-auto* janitor = new Janitor();
-janitor->LinkToInstance(player);
-janitor->Add(players->PlayerAdded.Connect(OnPlayer));
-```
-
-Leaked connections duplicate effects: double coins, stacked cameras, lingering highlights.
-
-## 3. Check nil
-
-`FindFirstChild` returns `nullptr`. `WaitForChild` can hang. Prefer `FindFirstChild` plus an early return on the hot path.
-
-## 4. One writer for persisted data
-
-[DataService](libraries/dataservice.md) distinguishes `Get()` (merged, includes transient admin overlays) from `GetPersisted()` (what ProfileStore will save). Use `SetTransient` for test panels so you never persist cheat values. Only the server writes persisted paths. The save **shape** is your Template — the library does not ship `Currencies`.
-
-## 5. Buffers, not ad-hoc strings
-
-`Net` packs arguments into a `buffer`. That is smaller and typed. Do not `JSONEncode` a whole inventory on every heartbeat. Send deltas. Cap array lengths the client can send.
-
-## 6. Names are API
-
-Remote names (`Net::Event("Coins")`) are public protocol. Keep them `const`, short, and unique. Changing a name without a migration breaks old clients.
-
-Next: [organization](cpp-organization.md), [OOP](oop/index.md), [Examples](examples/index.md).

package/docs/cpp-types.md

@@ -1,68 +0,0 @@
----
-title: C++ types in Cluaupp
-sidebar_position: 10
----
-
-# Types
-
-Cluaupp is statically typed in the C++ you write and in the Luau it emits. A type is a contract: what a value is allowed to be, and what you are allowed to do with it.
-
-## Primitive map
-
-| C++ | Luau | Use for |
-| --- | --- | --- |
-| `int`, `float`, `double` | `number` | counts, damage, alpha |
-| `bool` | `boolean` | flags |
-| `string` / `const char*` | `string` | names, paths |
-| `void` | (no return) | procedures |
-| `auto` | inferred | when `new` or `GetService` makes the type obvious |
-| `Player*`, `Folder*`, … | `Player`, `Folder` | Instances |
-| `LuaArray<int>` / `vector<T>` | `{number}` | arrays (Template inventory, `GetPlayers`) |
-| `optional<T>` | `T?` | missing values (prefer `nullptr` on Instances) |
-| `Vector3`, `CFrame`, `UDim2` | same | datatypes |
-
-```cpp
-int coins = 10;
-bool loaded = false;
-auto* folder = new Folder(player);
-```
-
-```luau
-local coins: number = 10
-local loaded: boolean = false
-local folder: Folder = Instance.new("Folder")
-folder.Parent = player
-```
-
-## Pointers are Instances, not memory
-
-In Cluaupp, `Player*` does not mean “heap address”. It means “this is a Roblox Instance of class Player”. `->` becomes `.` for properties and `:` for engine/library methods.
-
-```cpp
-player->Name = "Kartz";
-player->FindFirstChild("leaderstats");
-```
-
-```luau
-player.Name = "Kartz"
-player:FindFirstChild("leaderstats")
-```
-
-There is no pointer arithmetic, no `delete`, no `std::unique_ptr`. Lifetime is Roblox’s: parented Instances live until `Destroy` or until a [Janitor](libraries/janitor.md) cleans them.
-
-## `nullptr`
-
-`nullptr` is `nil`. Always test before using a `FindFirstChild` result:
-
-```cpp
-auto* stats = player->FindFirstChild("leaderstats");
-if (stats == nullptr) {
-	return;
-}
-```
-
-## Why types matter
-
-Typos, wrong arguments, and `nil` indexing are the majority of live-game bugs. `--!strict` plus C++ types catch them in the editor. If a function takes `Player*`, do not pass a `string`. If a value is `const int`, do not assign to it later.
-
-Next: [const and immutability](cpp-const.md).

package/docs/examples/_category_.json

@@ -1,5 +0,0 @@
-{
-	"label": "Examples",
-	"position": 21,
-	"collapsed": false
-}

package/docs/examples/combat.md

@@ -1,31 +0,0 @@
----
-title: Combat (server validation)
-sidebar_position: 4
----
-
-# Combat
-
-Live source: [`examples/game/src/server/combat.server.clpp`](../../examples/game/src/server/combat.server.clpp). Language: [CL++](https://kartzrbx.github.io/CLPP/).
-
-This sample uses exclusive CL++:
-
-- `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); … }`
-
-The client never decides damage. Touched parts fire `OnHit`; the server prints combo and destroys the part.
-
-```clpp
-#include <clpp/roblox.clh>
-#include <clpp/libs/janitor.clh>
-
-struct CombatServer {
-	Janitor* janitor;
-	signal<Player*, int> OnHit;
-	void PlayerEntered(Player* player);
-	void BindPart(BasePart* part);
-	void WatchWorkspace();
-};
-```

package/docs/examples/data-boot.md

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

@@ -1,28 +0,0 @@
----
-title: HUD
-sidebar_position: 6
----
-
-# HUD
-
-Live source: [`examples/game/src/client/hud.client.clpp`](../../examples/game/src/client/hud.client.clpp). Fusion API: [CL++](https://kartzrbx.github.io/CLPP/).
-
-Client-only (`[[client]]`). `Fusion:scoped` / `Fusion:Value` / `Fusion:Computed` / `Fusion:New` build a coins label. `guard` fails if `LocalPlayer` is missing.
-
-```clpp
-#include <clpp/roblox.clh>
-#include <clpp/libs/fusion.clh>
-
-[[client]]
-void init() {
-	Players* players = GetService<Players>();
-	Player* localPlayer = players.LocalPlayer;
-	guard (localPlayer != null) else {
-		report("LocalPlayer missing");
-		return;
-	}
-	auto scope = Fusion:scoped();
-	auto coins = Fusion:Value(scope, 0);
-	coins(100);
-}
-```

package/docs/examples/index.md

@@ -1,38 +0,0 @@
----
-title: Examples
-sidebar_position: 1
----
-
-# Examples
-
-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/).
-
-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/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.
-
-## 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

@@ -1,69 +0,0 @@
----
-title: Leaderstats
-sidebar_position: 3
----
-
-# Leaderstats
-
-Canonical copy (three files): [Docs → Example: Leaderstats](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
-
-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.
-
-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 |
-| --- | --- |
-| 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. |
-
-## Header
-
-```cpp
-#pragma once
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/janitor.hpp>
-#include <cluaupp/libs/dataservice.hpp>
-
-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);
-};
-```
-
-## `PlayerEntered`
-
-```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(leaderstatsFolder, "Destroy", GetPlayerJanitorKey(player));
-}
-```
-
-`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).

package/docs/examples/shop.md

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

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