cluaupp 0.2.3 → 1.3.0

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,262 +0,0 @@
-# C++ → Luau syntax
-
-Cluaupp is not a full C++ compiler. It is a **subset** aimed at Roblox scripts, in the same spirit as roblox-ts (restricted TypeScript → Luau).
-
-Live grid of every construct: **[Language reference](https://kartzrbx.github.io/Cluaupp/docs/reference.html)**.
-
-Generated Luau follows the current language: [`local`](https://luau.org/getting-started), `const`, and `const function`. Injected `require` / `GetService` lines are `const`. `--!strict` is emitted only when the file has `#pragma strict` (or `"strict": true` in config). `#pragma nstrict` never emits it.
-
-## Files and includes
-
-- Extensions: `.cpp`, `.cc`, `.cxx`, `.c`, `.h`, `.hpp`, `.hh`
-- Tags: `*.server.cpp` → Script, `*.client.cpp` → LocalScript, `*.plugin.cpp` → Plugin, `*.legacy*` → Legacy, untagged → ModuleScript
-- Quoted `#include "Own.h"` (same stem as the `.cpp`) is **inlined**. Other quoted includes become `require` (Rojo path)
-- `#include <cluaupp/roblox.hpp>` is IntelliSense only. `#include <cluaupp/libs/janitor.hpp>` also injects `require(CluauppLibs.Janitor)`
-- `#pragma once` is ignored. Other macros are not expanded. `//` and `/* */` comments are stripped
-- `using …;` is skipped. `namespace { }` is flattened. `enum` / `template` / `typedef` / `extern` declarations are skipped
-
-## Types
-
-| C++ | Luau |
-| --- | --- |
-| `int` / `float` / `double` | `number` |
-| `bool` | `boolean` |
-| `string` | `string` (not `std::string`) |
-| `void` | no return annotation |
-| `auto` / `auto*` | inferred from `new` / `GetService` / datatype ctor |
-| `Player*` / `Folder*` | `Player` / `Folder` (Instance handle, not a heap address) |
-| `LuaArray<T>` / `vector<T>` / `array<T>` / `span<T>` | `{T}` |
-| `optional<T>` | `T?` |
-| `const` / `static constexpr` | Luau `const` |
-| `nullptr` | `nil` |
-| `Vector3` `CFrame` `UDim2` `Color3` | same names (copied values) |
-| `Enum::Material::Plastic` | `Enum.Material.Plastic` |
-
-Always initialize: `int coins = 0;` not `int coins;` (uninitialized emits `nil`). There is no `delete`, no `*part`, no `&part`, no `int&`. Numbers copy; Instances mutate through `->`.
-
-`auto` infers when the value is `new Class(...)`, `GetService<T>()`, or a datatype constructor. Prefer explicit types on parameters and struct fields.
-
-## Functions
-
-```cpp
-void CreateLeaderstats(Player* player) {
-	return;
-}
-
-int doubleCoins(int coins) {
-	return coins;
-}
-```
-
-```luau
-const function CreateLeaderstats(player: Player)
-	return
-end
-
-const function doubleCoins(coins: number): number
-	return coins
-end
-```
-
-- Only functions with a body are emitted from a `.cpp`. Prototypes in a `.h` become `export type` fields
-- No overloading — one name, one emit. No default arguments
-- If `void init()` exists, emit appends `init()` at the end of Scripts / LocalScripts. There is no `int main()`
-- Shared ModuleScripts should not define `init()` unless you want them to run on `require`
-
-## Scopes
-
-- File-level decls become file `local` / `const`
-- Function decls become `local` from that line to the end of the block. Nested `{ }` can shadow
-- In `Class::Method`, `this` is `self`. Bare field names become `self.field`. Bare calls to other methods become `self:Method(...)`. Parameters and locals shadow fields
-- Globals stay bare: `print`, `game`, `workspace`, library types, Instance types, datatypes
-- Instances are not RAII. Leaving a block does not Destroy a Part — use Janitor
-
-## Control flow
-
-```cpp
-if (player->FindFirstChild("leaderstats") != nullptr) {
-	return;
-} else {
-	print("ok");
-}
-
-while (true) {
-	print("tick");
-}
-
-for (auto* player : players->GetPlayers()) {
-	CreateLeaderstats(player);
-}
-
-switch (action) {
-case "buy":
-case "purchase":
-	Grant(player);
-	break;
-case "sell":
-	if (amount <= 0) {
-		break;
-	}
-	Take(player);
-	break;
-default:
-	warn("unknown");
-	break;
-}
-```
-
-```luau
-if player:FindFirstChild("leaderstats") ~= nil then
-	return
-else
-	print("ok")
-end
-
-while true do
-	print("tick")
-end
-
-for _, player in players:GetPlayers() do
-	CreateLeaderstats(player)
-end
-
-repeat
-	if action == "buy" or action == "purchase" then
-		Grant(player)
-	elseif action == "sell" then
-		if amount <= 0 then
-			break
-		end
-		Take(player)
-	else
-		warn("unknown")
-	end
-until true
-```
-
-`switch` evaluates the discriminant **once**, then becomes `if` / `elseif` / `else` inside `repeat … until true` so `break` still exits the switch (even from inside an `if`). Stacked `case` labels share a body. There is no C-style fall-through. C-style `for (int i = 0; i < n; i++)` is not supported. No `continue`, no `do/while`, no ternary. `else if (x)` emits a nested `if` inside `else` (not Luau `elseif`).
-
-## Expressions and operators
-
-| C++ | Luau |
-| --- | --- |
-| `nullptr` | `nil` |
-| `true` / `false` | `true` / `false` |
-| `!=` | `~=` |
-| `&&` | `and` |
-| `\|\|` | `or` |
-| `!` | `not` |
-| `==` `+` `-` `*` `/` `<` `>` `<=` `>=` | same (`*` is multiply) |
-| `"text"` | `"text"` |
-| `=` | assignment |
-| `obj->Prop` | `obj.Prop` |
-| `obj->Method(a)` | `obj:Method(a)` if the method is a Roblox / library API |
-| `fn(a)` | `fn(a)` |
-| `signal.Connect(fn)` | `signal:Connect(fn)` |
-| `Type { .Field = value }` | `{ Field = value }` |
-| unary `-` | `-` |
-
-No `++` `--` `+=`. Write `n = n + 1`. Binary operators in this subset are left-associative — use parentheses when mixing.
-
-Designated initializers become Luau tables:
-
-```cpp
-DataService::Server.Init(DataServiceOptions {
-	.Template = playerData,
-	.StoreName = "PlayerData",
-	.UseMock = true,
-});
-```
-
-```luau
-DataService.Server:Init({
-	Template = playerData,
-	StoreName = "PlayerData",
-	UseMock = true,
-})
-```
-
-## Strings and string_concat
-
-Luau concatenates with `..`. Do not write `..` in a `.cpp`.
-
-- If either side of `+` is a string literal, another concat, or `.Name` / `.Text` / `.DisplayName`, `+` becomes `..`
-- `string_concat(a, b, c)` is variadic: zero args → `""`, one arg → that value, several → `(a .. b .. c)`
-- Declared in `datatypes.hpp` (via `roblox.hpp`)
-
-```cpp
-return player->Name + "_LeaderstatsJanitor";
-return string_concat(player->Name, "_", "LeaderstatsJanitor");
-```
-
-```luau
-return player.Name .. "_LeaderstatsJanitor"
-return (player.Name .. "_" .. "LeaderstatsJanitor")
-```
-
-## print / cout
-
-`print`, `warn`, and `error` work as in Luau. `cout << … << endl` is the C++ spelling — each `<<` is another argument, `endl` ends the line. `cout::warn` / `cout::error` / `cout::ping` pick the Roblox function. `cerr` is `warn`. Full table: [print and cout](print-cout.md).
-
-## `new` and services
-
-```cpp
-auto* coins = new IntValue(leaderstats);
-auto* players = GetService<Players>();
-auto* janitor = new Janitor();
-part->Size = Vector3(8, 1, 8);
-part->CFrame = CFrame::lookAt(from, look);
-part->Material = Enum::Material::Plastic;
-```
-
-```luau
-local coins: IntValue = Instance.new("IntValue")
-coins.Parent = leaderstats
-local players: Players = game:GetService("Players")
-local janitor = Janitor.new()
-part.Size = Vector3.new(8, 1, 8)
-part.CFrame = CFrame.lookAt(from, look)
-part.Material = Enum.Material.Plastic
-```
-
-The first argument of `new Class(parent)` becomes `.Parent` for Instance classes. Libraries use `Janitor.new()`. Datatypes use `Vector3(...)`, not `new`.
-
-## Casts
-
-`static_cast<T>(x)`, `const_cast`, `reinterpret_cast`, `dynamic_cast` emit the argument. `(void)x;` is omitted (silences unused for clangd). Luau has no casts — they do not check ClassName.
-
-## Callbacks (events and lambdas)
-
-Signals use `.Connect`. Callbacks may be **named functions** or **lambdas** (`[](Player* player) { ... }`, including `[&]` / `[=]` / `[coinsValue]`). Capture lists are accepted; Luau closures do not copy C++ captures — keep Instances alive with Janitor.
-
-Passing a method by name from inside `Class::` binds `self`: `function(...) self:OnPlayer(...) end`.
-
-```cpp
-players->PlayerAdded.Connect([&](Player* playerEntered) {
-	leaderstatsServer.PlayerEntered(playerEntered);
-});
-game->BindToClose([&]() {
-	leaderstatsServer.janitor->Cleanup();
-});
-```
-
-## OOP: structs, methods, singletons
-
-How you write a type: a `struct` (or `class`) in the sibling `.h`, `Class::Method` in the `.cpp`, `void init()` to boot.
-
-- `static constexpr` fields are `const`
-- Fields are `self.field`. `public:` / `private:` are ignored
-- Nested structs with defaults become nested tables (DataService Templates). `LuaArray<T>` fields stay on the table
-- `Class::` methods emit `function Class:Method(...)`
-- Construct **one** service table in `init()` (`LeaderstatsServer leaderstatsServer;`) and capture it in lambdas. That is the game singleton
-- Library singletons already exist: `DataService::Server` / `Client` — `Init` once from a boot script
-- Header-only field structs emit `const function Name()` returning defaults
-- Untagged files of only `Class::` methods `return` the table (ModuleScript)
-
-Stem must match: `LeaderstatsServer.h` next to `LeaderstatsServer.server.cpp`. A differently named include is a `require`, not the class body.
-
-## Not supported
-
-Custom C++ classes as metatables, generic templates besides `GetService<T>` / `static_cast<T>` / `LuaArray<T>` / `string_concat`, pointer arithmetic, `std::` (except mapped aliases), overloading, macros (except `#pragma strict` / `#pragma nstrict` / `#pragma once`), JSX / XML UI tags, C-style `for`, `++` `--` `+=`, `continue`, ternary, `do/while`, `try/catch`, `goto`, `int&` references.
-
-CLI forms: [CLI](cli.md). How to write a type: [OOP](oop/index.md). Full handbook: **[Docs](https://kartzrbx.github.io/Cluaupp/docs/)**.

package/examples/game/.clangd

@@ -1,25 +0,0 @@
-CompileFlags:
-  CompilationDatabase: .
-  Add:
-    - -xc++
-    - -std=c++20
-    - -ferror-limit=0
-    - -Iinclude
-    - -Isrc
-    - -I../../include
-
-Diagnostics:
-  Suppress: '*'
-
----
-If:
-  PathMatch: .*\.(cpp|cc|cxx|c|h|hpp|hh)$
-CompileFlags:
-  Add:
-    - -xc++
-
----
-If:
-  PathMatch: (out|libs)/.*
-Index:
-  Background: Skip

package/examples/game/compile_flags.txt

@@ -1,6 +0,0 @@
--xc++
--std=c++20
--ferror-limit=0
--Iinclude
--Isrc
--I../../include

package/examples/game/src/client/hud.client.cpp

@@ -1,12 +0,0 @@
-#pragma strict
-#include <cluaupp/roblox.hpp>
-
-void init() {
-	auto* playerGui = GetService<Players>()->LocalPlayer->FindFirstChild("PlayerGui");
-	auto* screen = new ScreenGui();
-	screen->Name = "Hud";
-	auto* coins = new TextLabel();
-	coins->Name = "Coins";
-	coins->Parent = screen;
-	print("hud ready");
-}

package/examples/game/src/client/init.client.cpp

@@ -1,6 +0,0 @@
-#pragma strict
-#include <cluaupp/roblox.hpp>
-
-void init() {
-	print("Cluaupp client ok");
-}

package/examples/game/src/server/combat.server.cpp

@@ -1,23 +0,0 @@
-#pragma strict
-#include <cluaupp/roblox.hpp>
-
-void ApplyDamage(Player* player, int amount) {
-	auto* character = player->Character;
-	if (character == nullptr) {
-		return;
-	}
-	auto* humanoid = character->FindFirstChildOfClass("Humanoid");
-	if (humanoid == nullptr) {
-		return;
-	}
-	humanoid->TakeDamage(amount);
-}
-
-void OnPlayer(Player* player) {
-	ApplyDamage(player, 0);
-}
-
-void init() {
-	auto* players = GetService<Players>();
-	players->PlayerAdded.Connect(OnPlayer);
-}

package/examples/game/src/server/leaderstats.server.cpp

@@ -1,29 +0,0 @@
-#pragma strict
-#include <cluaupp/roblox.hpp>
-
-void CreateLeaderstats(Player* player) {
-	if (player->FindFirstChild("leaderstats") != nullptr) {
-		return;
-	}
-
-	auto* leaderstats = new Folder(player);
-	leaderstats->Name = "leaderstats";
-
-	auto* coins = new IntValue(leaderstats);
-	coins->Name = "Coins";
-	coins->Value = 0;
-
-	auto* level = new IntValue(leaderstats);
-	level->Name = "Level";
-	level->Value = 0;
-}
-
-void init() {
-	auto* players = GetService<Players>();
-
-	for (auto* player : players->GetPlayers()) {
-		CreateLeaderstats(player);
-	}
-
-	players->PlayerAdded.Connect(CreateLeaderstats);
-}

package/examples/game/src/shared/config.cpp

@@ -1,5 +0,0 @@
-#include "config.h"
-
-int startingCoins() {
-	return STARTING_COINS;
-}

package/examples/game/src/shared/config.h

@@ -1,5 +0,0 @@
-#include <cluaupp/roblox.hpp>
-
-const int STARTING_COINS = 0;
-
-int startingCoins();

package/include/cluaupp/libs/chrono.hpp

@@ -1,26 +0,0 @@
-#pragma once
-
-// Parihsz/Chrono — custom character replication, vendored into CluauppLibs.Chrono
-class ChronoHolder {};
-class ChronoEntity {};
-class ChronoStats {};
-class ChronoConfig {};
-class ChronoReplicationRules {};
-class ChronoEvents {};
-class ChronoSnapshots {};
-class ChronoServerClock {};
-class ChronoPlayer {};
-
-namespace Chrono {
-	void Start();
-	void Start(ModuleScript* config);
-	ChronoHolder* Holder();
-	ChronoEntity* Entity();
-	ChronoStats* Stats();
-	ChronoConfig* Config();
-	ChronoReplicationRules* ReplicationRules();
-	ChronoEvents* Events();
-	ChronoSnapshots* Snapshots();
-	ChronoServerClock* ServerClock();
-	ChronoPlayer* Player();
-}

package/include/cluaupp/libs/cmdr.hpp

@@ -1,16 +0,0 @@
-#pragma once
-
-// evaera/Cmdr — vendored into CluauppLibs.Cmdr (server). Client: Cmdr.CmdrClient
-class CmdrType {};
-class CmdrCommand {};
-class CmdrRegistry {};
-class CmdrDispatcher {};
-
-namespace Cmdr {
-	void RegisterDefaultCommands();
-	void RegisterHook(string name, void (*callback)());
-	void RegisterType(string name, CmdrType* typeDefinition);
-	void RegisterCommand(CmdrCommand* commandDefinition);
-	CmdrRegistry* Registry();
-	CmdrDispatcher* Dispatcher();
-}

package/include/cluaupp/libs/ezvisual.hpp

@@ -1,18 +0,0 @@
-#pragma once
-
-// arxkdev/ezVisualz — EasyVisuals, vendored into CluauppLibs.EzVisualz
-// Effect.new(gui, "Rainbow", speed, size)
-class EzVisualz {
-public:
-	static EzVisualz* new_(GuiObject* target, string effectType);
-	static EzVisualz* new_(GuiObject* target, string effectType, double speed, double size);
-	void Play();
-	void Pause();
-	void Resume();
-	void Stop();
-	void Destroy();
-	GuiObject* UIInstance;
-	double Speed;
-	double Size;
-	bool IsPaused;
-};

package/include/cluaupp/libs/promise.hpp

@@ -1,30 +0,0 @@
-#pragma once
-
-// evaera/roblox-lua-promise — vendored into CluauppLibs.Promise
-// C++ Then/Catch/Await/Cancel map onto andThen/catch/await/cancel.
-class Promise {
-public:
-	Promise(void (*executor)());
-	template <typename T>
-	static Promise* resolve(T value);
-	static Promise* reject(string err);
-	static Promise* delay(double seconds);
-	static Promise* try_(void (*callback)());
-	static Promise* all(LuaArray<Promise*> list);
-	static Promise* race(LuaArray<Promise*> list);
-	static Promise* retry(void (*callback)(), int times);
-	Promise* Then(void (*ok)());
-	Promise* Catch(void (*fail)());
-	Promise* Finally(void (*callback)());
-	Promise* andThen(void (*ok)());
-	Promise* catch_(void (*fail)());
-	Promise* finally(void (*callback)());
-	template <typename T>
-	T Await();
-	template <typename T>
-	T await();
-	void Cancel();
-	void cancel();
-	string GetStatus();
-	string getStatus();
-};