cluaupp 1.0.0 → 1.3.0

package/docs/oop/modules.md

@@ -1,88 +0,0 @@
----
-title: Modules and structs
-sidebar_position: 4
----
-
-# Modules and structs
-
-Use this when you want a **reusable object** without a tagged Script.
-
-## Untagged `.cpp` = ModuleScript
-
-```
-src/shared/util/Coins.cpp
-```
-
-```cpp
-#include <cluaupp/roblox.hpp>
-
-int DoubleCoins(int coins) {
-	return coins;
-}
-```
-
-```
-out/shared/util/Coins.luau   -- ModuleScript, exported functions
-```
-
-Quoted `#include "TemplateData.hpp"` is not inlined when the header has a sibling `.cpp` or is a shared module: `cluaupp build` emits `require(ReplicatedStorage.Cluaupp.constants.TemplateData)` / `require(ServerScriptService.Cluaupp.configurations.PlayerDataVersion)` (Rojo roots from `default.project.json`), never `script.Parent.Parent.shared`.
-
-`.h` / `.hpp` are **type modules**. A service header becomes `export type Name = { init: (self: Name) -> (), … }` and a typed table. The sibling `.cpp` is the construction (`NameImpl.luau`); the header `require`s that impl and binds the functions. Data-only structs still emit a constructor so `TemplateData()` works. Untagged `.cpp` without a header is a ModuleScript other Luau can `require`. Prefer headers for the public type, tagged `.server.cpp` / `.client.cpp` for scripts, and the sibling `.cpp` for method bodies.
-
-## Structs = data, not classes
-
-The subset allows structs for IntelliSense and designated initializers (tables):
-
-```cpp
-struct TemplateData {
-	struct Currencies {
-		int Money = 0;
-		int Level = 1;
-	} Currencies;
-};
-
-TemplateData playerData = TemplateData {};
-```
-
-That is your “class fields”. Methods are **named functions** next to them (`EnsureStat`, `ApplyCurrencies`). Cluaupp does not emit `function TemplateData:GetMoney()`.
-
-## Methods as functions
-
-```cpp
-void EnsureStat(Folder* folder, string name, int value) {
-	auto* stat = folder->FindFirstChild(name);
-	if (stat == nullptr) {
-		cout::print << "EnsureStat: " << name << " not found" << endl;
-		return;
-	}
-}
-```
-
-Pass the instance in (`folder`, `player`). That is composition: the Folder is the object, the function is the method.
-
-## Janitor as the destructor
-
-There is no C++ destructor. Pair “construct” with a Janitor:
-
-```cpp
-auto* janitor = new Janitor();
-janitor->LinkToInstance(player);
-janitor->Add(player->AncestryChanged.Connect(OnAncestry));
-```
-
-When the player leaves, `LinkToInstance` runs `Cleanup`. That is RAII for Roblox.
-
-## Start / Stop
-
-On generated services, `Main.Start` / `Main.Stop` are the constructor / destructor of the **system**. Put connections in Start (or in `init()` / `PlayersManager`). Do not leak `Connect` without a Janitor.
-
-## What not to write
-
-```cpp
-class Shop {
-	int price;
-	void Buy(Player* player);
-};
-```
-
-Custom classes are **not supported**. Split into a struct (fields) + functions (methods) + a `.server.cpp` or untagged module (lifetime).

package/docs/oop/services.md

@@ -1,76 +0,0 @@
----
-title: Services
-sidebar_position: 3
----
-
-# Services
-
-Write **one tagged file per system**. Cluaupp emits **one** Luau instance: `LeaderstatsServer.server.luau` from `LeaderstatsServer.server.cpp`. It does not invent Main / Controller / Types unless `"architecture": true`.
-
-## Example: leaderstats
-
-```cpp
-#include <cluaupp/roblox.hpp>
-#include <cluaupp/libs/janitor.hpp>
-#include <cluaupp/libs/dataservice.hpp>
-
-void EnsureStat(Folder* folder, string name, int value) {
-	return;
-}
-
-void ApplyCurrencies(Player* player, Data* data) {
-	return;
-}
-
-void OnCurrenciesChanged() {
-	return;
-}
-
-void SetupPlayerManager(Player* player) {
-	Data* data = DataService::Server.WaitFor(player);
-	if (data == nullptr) {
-		return;
-	}
-	ApplyCurrencies(player, data);
-	data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged);
-}
-
-void init() {
-	auto* players = GetService<Players>();
-	players->PlayerAdded.Connect(SetupPlayerManager);
-}
-```
-
-Typical output:
-
-```
-out/server/services/leaderstats/LeaderstatsServer.server.luau
-```
-
-Your functions stay in that file. `init()` runs at the end. There is no fake `Main` that only forwards to a Controller.
-
-## Lifecycle
-
-You own `init` and Janitor cleanup in the same file. You do not write `class LeaderstatsServer` — name the **file** `LeaderstatsServer.server.cpp` and keep **functions** as the public API.
-
-`"architecture": true` is the old ForeverHD split (`Main.Start` / `Main.Stop`, Managers, Types). Leave it off unless you want that.
-
-## Boot vs gameplay
-
-Keep DataService `Init` in `DataBoot.server.cpp` / `DataBoot.client.cpp`. Keep leaderstats / combat in their own `.server.cpp`. Services `WaitFor` after boot has run.
-
-## Opt-in roles (`"architecture": true`)
-
-| Your C++ | Generated role |
-| --- | --- |
-| `PlayerAdded`, `GetPlayers` | `PlayersManager` |
-| `Folder` + `IntValue` | `CacheController` |
-| `DataService`, `GetChangedSignal` | `DataController` |
-| `TakeDamage`, `Humanoid` | `CombatController` |
-| `Net::Event` | `NetController` |
-| `UserInputService` | `InputController` |
-| wiring | `Main.Start` / `Main.Stop` |
-
-A tiny `print` in `init.client.cpp` stays a single LocalScript.
-
-Copy-paste: [Examples](../examples/index.md).

package/docs/print-cout.md

@@ -1,91 +0,0 @@
----
-title: print and cout
-sidebar_position: 8
----
-
-# print and cout
-
-Cluaupp has no `<iostream>`. Logging is Roblox `print` / `warn` / `error`. You can still write C++-style `cout` / `cerr` / `endl` — the compiler flattens them.
-
-## Globals
-
-```cpp
-print("ok");
-warn("careful");
-error("fail");
-```
-
-```luau
-print("ok")
-warn("careful")
-error("fail")
-```
-
-`print` in C++ takes a string (and chained `cout` pieces). Do not expect full C++ `std::cout` overloads.
-
-## Stream: `cout << … << endl`
-
-Each `<<` is another argument. `endl` ends the statement (no extra `"\n"`).
-
-```cpp
-cout << "EnsureStat: " << name << " not found" << endl;
-```
-
-```luau
-print("EnsureStat: ", name, " not found")
-```
-
-`cerr` is the same chain, emitted as `warn`:
-
-```cpp
-cerr << "failed to load " << player->Name << endl;
-```
-
-```luau
-warn("failed to load ", player.Name)
-```
-
-## Levels: `cout::print` / `warn` / `error` / `ping`
-
-Use `::` to pick the Roblox function. The stream still concatenates with `<<`.
-
-```cpp
-cout::print << "EnsureStat test: " << name << " not found" << endl;
-cout::warn << "missing folder for " << player->Name << endl;
-cout::error << "profile failed" << endl;
-cout::ping << "here" << endl;
-```
-
-```luau
-print("EnsureStat test: ", name, " not found")
-warn("missing folder for ", player.Name)
-error("profile failed")
-print("here")
-```
-
-| C++ | Luau |
-| --- | --- |
-| `cout << … << endl` | `print(…)` |
-| `cout::print << … << endl` | `print(…)` |
-| `cout::warn << … << endl` | `warn(…)` |
-| `cout::error << … << endl` | `error(…)` |
-| `cout::ping << … << endl` | `print(…)` |
-| `cerr << … << endl` | `warn(…)` |
-
-`cout::ping` is a debug alias of `print` (no extra Studio highlight).
-
-## Call form (no `<<`)
-
-```cpp
-cout::print("ok");
-cout::warn("careful");
-cout::error("fail");
-cout::ping("here");
-cout::endl();
-```
-
-`cout::endl()` is a no-op in Luau (flush is already the statement). Prefer `<< endl` on a stream.
-
-## IntelliSense
-
-`struct cout` / `cerr` and `endl` live in `<cluaupp/roblox.hpp>`. Include that header so clangd knows `cout::print` and `operator<<`.

package/docs/roblox-api.md

@@ -1,29 +0,0 @@
-# Roblox API
-
-Cluaupp uses the official engine. Spell the call in C++; look up members on [create.roblox.com](https://create.roblox.com/docs/reference/engine). The GitHub Pages site is a **language handbook**, not a dump of every Enum item.
-
-Handbook: **[Docs](https://kartzrbx.github.io/Cluaupp/docs/)** · [Roblox in Cluaupp](https://kartzrbx.github.io/Cluaupp/docs/engine.html)
-
-`#include <cluaupp/roblox.hpp>` is IntelliSense. The compiler ignores the header and emits real Luau.
-
-## Datatypes
-
-```cpp
-part->Size = Vector3(8, 1, 8);
-part->Position = Vector3(0, 10, 0);
-part->CFrame = CFrame::lookAt(Vector3(0, 10, 0), Vector3(0, 10, -10));
-part->Color = Color3::fromRGB(255, 0, 0);
-frame->Size = UDim2::fromScale(1, 1);
-auto material = Enum::Material::Plastic;
-```
-
-```luau
-part.Size = Vector3.new(8, 1, 8)
-part.Position = Vector3.new(0, 10, 0)
-part.CFrame = CFrame.lookAt(Vector3.new(0, 10, 0), Vector3.new(0, 10, -10))
-part.Color = Color3.fromRGB(255, 0, 0)
-frame.Size = UDim2.fromScale(1, 1)
-local material = Enum.Material.Plastic
-```
-
-Every enum is `Enum::Name::Item` → `Enum.Name.Item`. Services are `GetService<Players>()`. Instances are `new Folder(parent)` and `player->FindFirstChild("x")`.

package/docs/syntax.md

@@ -1,80 +0,0 @@
-# CL++ syntax (Cluaupp)
-
-Cluaupp does **not** define the language. Write CL++ (`.clpp` / `.clp` / `.clh`); `clpp` emits Luau. Full course and reference: **[kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/)**.
-
-## Files
-
-| Source | Rojo |
-| --- | --- |
-| `*.server.clpp` | Script |
-| `*.client.clpp` | LocalScript |
-| `*.plugin.clpp` | Plugin Script |
-| `*.clp` / untagged `.clpp` | ModuleScript |
-| `*.clh` | ModuleScript (types / structs) |
-
-`void init()` is the script entry. There is no `int main()`.
-
-## Accessors
-
-CL++ does **not** use `->`.
-
-| Write | Meaning | Luau |
-| --- | --- | --- |
-| `player.Name` | property | `.` |
-| `player::FindFirstChild("x")` | method | `:` |
-| `DataService:Server` | table key | `.` |
-| `"hi " .: name` | concat | `..` |
-| `signal~>Connect(fn)` | janitor Connect | `janitor:Add(..., "Disconnect")` |
-| `signal~>Once(fn)` | one-shot | `Once` + janitor |
-
-`post` / `warn` / `report` → `print` / `warn` / `error`. `null` is `nil`.
-
-## Exclusive CL++ (compiled by `clpp`)
-
-```clpp
-guard (player != null) else {
-	warn("Invalid player");
-	return;
-}
-
-match (child) {
-	BasePart* p => BindPart(p),
-	Model* m => post("model spawned " .: m.Name),
-	_ => warn("ignored instance")
-};
-
-observable int wallet = 100;
-wallet.OnChange(func [](int newValue) {
-	post("Coins changed to: " .: newValue);
-});
-
-signal<Player*, int> OnHit;
-OnHit~>Connect(func [](Player* player, int amount) {
-	post(player.Name .: " dmg " .: amount);
-});
-OnHit::Fire(player, 10);
-
-array<string> names = {"Kartz", "Player1"};
-dictionary<string, int> stats = { {"Coins", 100}, {"Gems", 50} };
-
-spawn { task::wait(1); post("ready"); };
-parallel { post("desync"); };
-
-async Data* FetchData(Player* player) {
-	return await DataService:Server::WaitFor(player);
-}
-
-[[server]]
-void SaveData(Player* player) { post(player.Name); }
-
-[[client]]
-void UpdateUI() { post("ui"); }
-```
-
-Fusion HUD uses `Fusion:scoped`, `Fusion:Value`, `Fusion:Computed`, `Fusion:New`. See [`examples/game`](../examples/game) (`combat.server.clpp`, `hud.client.clpp`, `features.clp`, `PlayerData.clh`).
-
-## What Cluaupp adds after `clpp`
-
-- `require(ClppLibs.X)` → `require(ReplicatedStorage.CluauppLibs.X)`
-- `--!strict` from `cluaupp.config.json` / `#pragma strict`
-- `out/` layout for Rojo (`init`, `build`, `watch`)