cluaupp 0.1.0

package/docs/cpp-safety.md

@@ -0,0 +1,58 @@
+---
+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.md) lets a client `FireServer`. The server must validate:
+
+```cpp
+void OnBuy(Player* player, int productId) {
+	if (productId < 1) {
+		return;
+	}
+	int price = PriceOf(productId);
+	int coins = DataService::Get(player, "Currencies.Coins");
+	if (coins < price) {
+		return;
+	}
+	DataService::Set(player, "Currencies.Coins", coins - price);
+}
+```
+
+Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`).
+
+## 2. Clean up with Janitor
+
+Every `Connect` that outlives a player, a GUI, or a tool needs a Janitor. 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
+
+[DataServiceV2](https://wally.run/package/kartzrbx/dataservicev2) 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.
+
+## 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).

package/docs/cpp-types.md

@@ -0,0 +1,66 @@
+---
+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 |
+| `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.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/getting-started.md

@@ -0,0 +1,169 @@
+# Getting started
+
+Cluaupp installs from **npm**, the same channel as roblox-ts and most Roblox tooling outside Studio.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) 18 or newer
+- [Rojo](https://rojo.space/) to sync `out/` into Studio
+- An editor with C++ IntelliSense (Cursor / VS Code + the C/C++ extension)
+
+## Install the compiler
+
+Global (`cluaupp` on your PATH):
+
+```bash
+npm install -g cluaupp
+cluaupp --version
+```
+
+Without a global install, via `npx`:
+
+```bash
+npx cluaupp init my-game
+```
+
+As a game dependency:
+
+```bash
+npm install --save-dev cluaupp
+```
+
+```json
+{
+	"scripts": {
+		"build": "cluaupp build",
+		"watch": "cluaupp watch"
+	}
+}
+```
+
+## First game
+
+```bash
+cluaupp init my-game
+cd my-game
+cluaupp build
+rojo serve
+```
+
+In Roblox Studio: install the Rojo plugin and connect to `localhost:34872` (default port).
+
+Generated layout:
+
+```
+my-game/
+  cluaupp.config.json
+  default.project.json    ← Rojo
+  include/cluaupp/roblox.hpp
+  include/cluaupp/libs/
+  libs/                   ← CluauppLibs (Janitor, Fusion, Cmdr, DataService, …)
+  Packages/               ← optional extra Wally
+  wally.toml
+  src/
+    server/leaderstats.server.cpp
+    client/init.client.cpp
+    shared/config.h
+    shared/config.cpp
+  out/                    ← generated Luau (do not edit)
+    server/LeaderStats/     Main, PlayersManager, CacheController, Types
+    shared/Config.luau
+```
+
+## Datatypes (Vector3, CFrame, UDim2)
+
+```cpp
+#include <cluaupp/roblox.hpp>
+
+void init() {
+	auto* part = new Part(workspace);
+	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);
+	part->Material = Enum::Material::Plastic;
+
+	auto* frame = new Frame();
+	frame->Size = UDim2::fromScale(1, 1);
+	frame->Position = UDim2(0, 0, 0.5, 0);
+}
+```
+
+This becomes `Vector3.new`, `CFrame.lookAt`, `Color3.fromRGB`, `UDim2.fromScale`, `Enum.Material.Plastic`.
+
+Full reference (every class from [create.roblox.com](https://create.roblox.com/docs/reference/engine)): [Cluaupp GitHub Pages](https://kartzrbx.github.io/Cluaupp/).
+
+## How to write
+
+Every `.cpp` / `.h` / `.hpp` file can start with the IntelliSense header. Angle-bracket includes are ignored. Quoted `#include "config.h"` is inlined into the file.
+
+```cpp
+#include <cluaupp/roblox.hpp>
+
+void CreateLeaderstats(Player* player) {
+	if (player->FindFirstChild("leaderstats") != nullptr) {
+		return;
+	}
+
+	auto* leaderstats = new Folder(player);
+	leaderstats->Name = "leaderstats";
+}
+
+void init() {
+	auto* players = GetService<Players>();
+	for (auto* player : players->GetPlayers()) {
+		CreateLeaderstats(player);
+	}
+	players->PlayerAdded.Connect(CreateLeaderstats);
+}
+```
+
+If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau`. Use that in Scripts and LocalScripts.
+
+## IntelliSense
+
+`cluaupp init` copies `include/cluaupp/roblox.hpp`, `.vscode/c_cpp_properties.json`, and `compile_flags.txt` (clangd). `cluaupp build` refreshes `include/cluaupp/` so completions stay in sync with the compiler.
+
+In this repo the include path is `cluau/include` (and `game/include`). After opening a `.cpp` file, complete `Player`, `FindFirstChild`, `GetPlayers`, and `Vector3`.
+
+The header is **not** compiled to Luau; it only feeds the C++ language server. Use `#include <cluaupp/roblox.hpp>` at the top of each source file.
+
+Reload the window (Command Palette → **Developer: Reload Window**) if completions were missing before the include path existed.
+
+## Watch
+
+```bash
+cluaupp watch
+```
+
+Saving a `.cpp`, `.h`, or `.hpp` under `src/` rebuilds the project. Keep Rojo running at the same time.
+
+## Libraries
+
+`cluaupp build` copies runtime modules to `libs/` (Rojo: `ReplicatedStorage.CluauppLibs`). Include a header and the compiler injects `require`.
+
+```cpp
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/net.hpp>
+
+void init() {
+	auto* janitor = new Janitor();
+	auto* coins = Net::Event("Coins");
+	janitor->Add(coins);
+}
+```
+
+Wally is optional. Fusion, Cmdr, DataServiceV2, and the rest ship **inside** `libs/` (full GitHub source). See [Libraries](libraries.md).
+
+See [Libraries](libraries.md), [types](cpp-types.md), [safety](cpp-safety.md).
+
+## Next
+
+- [C++ → Luau syntax](syntax.md)
+- [C++ types](cpp-types.md)
+- [const](cpp-const.md)
+- [Safety](cpp-safety.md)
+- [Organization](cpp-organization.md)
+- [Architecture](architecture.md)
+- [Roblox API](roblox-api.md)
+- [CLI](cli.md)

package/docs/intro.md

@@ -0,0 +1,37 @@
+---
+title: Cluaupp
+sidebar_position: 1
+---
+
+# Cluaupp
+
+**The definitive merge of C++ and modern Luau.** You write a C++ subset. Cluaupp emits [Luau](https://luau.org/getting-started) with `--!strict`, `local`, and `const`, and calls the Roblox API the way Studio does.
+
+This site is built with [Moonwave](https://eryn.io/moonwave/) for local markdown docs (`npm run docs`). The public site is the cinematic engine dump at [GitHub Pages](https://kartzrbx.github.io/Cluaupp/). The language is in the same spirit as [roblox-ts](https://roblox-ts.com): a familiar syntax, a restricted subset, readable output.
+
+## What you get
+
+1. A compiler (`cluaupp init` / `build` / `watch`)
+2. Headers for IntelliSense (`#include <cluaupp/roblox.hpp>`)
+3. First-party libraries in `ReplicatedStorage.CluauppLibs`
+4. Wally wrappers for DataServiceV2, Fusion, Cmdr, EzVisualz, TopbarPlus, and the rest of your stack
+
+## First program
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+
+void OnPlayer(Player* player) {
+	auto* janitor = new Janitor();
+	janitor->LinkToInstance(player);
+	janitor->Add(player->AncestryChanged.Connect(OnPlayer));
+}
+
+void init() {
+	auto* players = GetService<Players>();
+	players->PlayerAdded.Connect(OnPlayer);
+}
+```
+
+Read [Getting started](getting-started.md), then [C++ types](cpp-types.md) and [Libraries](libraries.md).

package/docs/libraries.md

@@ -0,0 +1,77 @@
+---
+title: Libraries
+sidebar_position: 20
+---
+
+# Libraries
+
+Cluaupp ships **full library systems** in `CluauppLibs` (`runtime/` → `libs/` on `cluaupp init` / `build`). These are not typings and not `require(Packages.*)` stubs. `cluaupp build` copies the Luau source. `#include <cluaupp/libs/...>` injects `require(ReplicatedStorage.CluauppLibs.<Name>)`.
+
+Re-vendor from GitHub:
+
+```bash
+cd cluau
+# clones live in vendor/ (gitignored)
+node scripts/vendor-libs.js
+```
+
+Sources: [runtime/SOURCES.md](https://github.com/kartzDev/cluaupp/blob/main/runtime/SOURCES.md).
+
+## Vendored from GitHub
+
+| Library | Header | GitHub | What you get |
+| --- | --- | --- | --- |
+| **Janitor** | `<cluaupp/libs/janitor.hpp>` | [howmanysmall/Janitor](https://github.com/howmanysmall/Janitor) | Add / AddPromise / LinkToInstance / Cleanup |
+| **Promise** | `<cluaupp/libs/promise.hpp>` | [evaera/roblox-lua-promise](https://github.com/evaera/roblox-lua-promise) | andThen + Cluaupp aliases Then / Catch / Await |
+| **Fusion** | `<cluaupp/libs/fusion.hpp>` | [dphfox/Fusion](https://github.com/dphfox/Fusion) | scoped, New, Value, Computed, Spring, Tween |
+| **Iris** | `<cluaupp/libs/iris.hpp>` | [SirMallard/Iris](https://github.com/SirMallard/Iris) | Immediate-mode debug UI |
+| **Cmdr** | `<cluaupp/libs/cmdr.hpp>` | [evaera/Cmdr](https://github.com/evaera/Cmdr) | Command console (server module + CmdrClient) |
+| **TopbarPlus** | `<cluaupp/libs/topbarplus.hpp>` | [1ForeverHD/TopbarPlus](https://github.com/1ForeverHD/TopbarPlus) | `Icon.new`, setLabel, dropdowns |
+| **Chrono** | `<cluaupp/libs/chrono.hpp>` | [Parihsz/Chrono](https://github.com/Parihsz/Chrono) | Custom character replication (`Chrono.Start()`) |
+| **DataService** | `<cluaupp/libs/dataservice.hpp>` | [KartzRbx/dataservicev2](https://github.com/KartzRbx/dataservicev2) | ProfileStore, QuickNet, Paths, Get vs GetPersisted |
+| **EzVisualz** | `<cluaupp/libs/ezvisual.hpp>` | [arxkdev/ezVisualz](https://github.com/arxkdev/ezVisualz) | UIGradient presets (Rainbow, Gold, …) |
+| **StateMachine** | `<cluaupp/libs/statemachine.hpp>` | [Prooheckcp/RobloxStateMachine](https://github.com/Prooheckcp/RobloxStateMachine) | States, transitions, LoadDirectory |
+| **Spring** | `<cluaupp/libs/spring.hpp>` | [nightcycle/spring](https://github.com/nightcycle/spring) | Damped spring (`new(damping, frequency, position)`) |
+| **Display** | `<cluaupp/libs/display.hpp>` | [nightcycle/display](https://github.com/nightcycle/display) | Pretty-print any value (`option` bundled) |
+| **Module3D** | `<cluaupp/libs/module3d.hpp>` | [TheNexusAvenger/Module3D](https://github.com/TheNexusAvenger/Module3D) | Model in a ViewportFrame |
+| **FormatNumber** | `<cluaupp/libs/formatnumber.hpp>` | [Blockzez/RobloxFormatNumber](https://github.com/Blockzez/RobloxFormatNumber) | ICU-style formatters + Abbreviate / Comma |
+
+## Cluaupp originals
+
+| Library | Header | Role |
+| --- | --- | --- |
+| **Net** | `<cluaupp/libs/net.hpp>` | Buffer-packed RemoteEvent / RemoteFunction |
+| **MathUtils** | `<cluaupp/libs/math.hpp>` | Lerp, Map, Clamp, angles |
+| **Twinkle** | `<cluaupp/libs/twinkle.hpp>` | UI fade / slide / zoom / bounce |
+| **StickyBillboard** | `<cluaupp/libs/stickybillboard.hpp>` | BillboardGui on an adornee (no public GitHub) |
+| **VfxUtil** | `<cluaupp/libs/vfx.hpp>` | Emit / Play / CloneOnto ParticleEmitters |
+| **ArrayIndexer** | (types) | `Table<Manifest, "Name">` |
+| **Occlude** | (types) | `Keys<Data, "field">` |
+
+```cpp
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+#include <cluaupp/libs/net.hpp>
+#include <cluaupp/libs/dataservice.hpp>
+#include <cluaupp/libs/formatnumber.hpp>
+
+void OnCoins(Player* player, int amount) {
+	auto* stats = player->FindFirstChild("leaderstats");
+	if (stats == nullptr) {
+		return;
+	}
+}
+
+void init() {
+	auto* janitor = new Janitor();
+	auto* coins = Net::Event("Coins");
+	coins->On(OnCoins);
+	print(FormatNumber::Abbreviate(1500));
+	DataService::Set(GetService<Players>()->GetPlayers()[0], "Currencies.Coins", 10);
+	janitor->Add(coins);
+}
+```
+
+Wally is **optional**. The game template no longer depends on Wally for these packages. Add Wally only for extra community packages you want beside CluauppLibs.
+
+Typed Luau borders live in `runtime/<Lib>/init.luau` (Janitor, Promise, Net, MathUtils, FormatNumber, Module3D, Twinkle). Engine classes: [API](https://kartzrbx.github.io/Cluaupp/api/classes/).

package/docs/roblox-api.md

@@ -0,0 +1,81 @@
+# Roblox API
+
+Cluaupp covers the engine API listed on [create.roblox.com](https://create.roblox.com/docs/reference/engine): **925 classes**, **636 enums**, and the datatypes (`Vector3`, `CFrame`, `UDim`, `UDim2`, …).
+
+The **page-by-page** reference (every property, method, and event, with C++ and Luau) lives on the generated site:
+
+**[Cluaupp docs (GitHub Pages)](https://kartzrbx.github.io/Cluaupp/)**
+
+- [Datatypes](https://kartzrbx.github.io/Cluaupp/api/datatypes/)
+- [Classes](https://kartzrbx.github.io/Cluaupp/api/classes/)
+- [Enums](https://kartzrbx.github.io/Cluaupp/api/enums/)
+
+In C++, `#include <cluaupp/roblox.hpp>`. 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);
+frame->Position = UDim2(0, 0, 0.5, 0);
+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)
+frame.Position = UDim2.new(0, 0, 0.5, 0)
+local material = Enum.Material.Plastic
+```
+
+| C++ | Luau |
+| --- | --- |
+| `Vector3(x, y, z)` | `Vector3.new(x, y, z)` |
+| `Vector2(x, y)` | `Vector2.new(x, y)` |
+| `CFrame(x, y, z)` | `CFrame.new(x, y, z)` |
+| `CFrame::lookAt(from, look)` | `CFrame.lookAt(from, look)` |
+| `UDim(scale, offset)` | `UDim.new(scale, offset)` |
+| `UDim2(xs, xo, ys, yo)` | `UDim2.new(xs, xo, ys, yo)` |
+| `UDim2::fromScale(x, y)` | `UDim2.fromScale(x, y)` |
+| `UDim2::fromOffset(x, y)` | `UDim2.fromOffset(x, y)` |
+| `Color3::fromRGB(r, g, b)` | `Color3.fromRGB(r, g, b)` |
+| `Color3::fromHSV(h, s, v)` | `Color3.fromHSV(h, s, v)` |
+| `BrickColor("Bright red")` | `BrickColor.new("Bright red")` |
+| `Enum::Material::Plastic` | `Enum.Material.Plastic` |
+| `Rect(x0, y0, x1, y1)` | `Rect.new(x0, y0, x1, y1)` |
+| `Ray(origin, direction)` | `Ray.new(origin, direction)` |
+| `NumberRange(min, max)` | `NumberRange.new(min, max)` |
+| `TweenInfo(time, style)` | `TweenInfo.new(time, style)` |
+
+## Instances and services
+
+```cpp
+auto* part = new Part(workspace);
+auto* players = GetService<Players>();
+player->FindFirstChild("leaderstats");
+players->GetPlayers();
+```
+
+```luau
+local part: Part = Instance.new("Part")
+part.Parent = workspace
+local players: Players = game:GetService("Players")
+player:FindFirstChild("leaderstats")
+players:GetPlayers()
+```
+
+`new Class(parent)` is for creatable classes (`Instance.new`). Services use `GetService<Name>()`.
+
+Generated headers (official client dump):
+
+- `include/cluaupp/datatypes.hpp`
+- `include/cluaupp/generated/enums.hpp`
+- `include/cluaupp/generated/instances.hpp`
+
+To regenerate: `npm run generate-api` in the `cluau/` folder.

package/docs/syntax.md

@@ -0,0 +1,131 @@
+# 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).
+
+Generated Luau follows the current language: [`--!strict`](https://luau.org/getting-started), `local`, and `const`.
+
+## Files
+
+- Extensions: `.cpp`, `.h`, `.hpp` (also `.cc`, `.hh`)
+- Quoted `#include "file.h"` is inlined (C preprocessor)
+- `#include <cluaupp/roblox.hpp>` and `<cluaupp/libs/*.hpp>` are IntelliSense only; library headers also inject `require(CluauppLibs.*)`
+- Other `#` lines (`#pragma once`) are ignored
+- Function prototypes (`void foo();`) are skipped; only functions with a body are emitted
+
+## Functions
+
+```cpp
+void CreateLeaderstats(Player* player) {
+	return;
+}
+
+int doubleCoins(int coins) {
+	return coins;
+}
+```
+
+```luau
+local function CreateLeaderstats(player: Player)
+	return
+end
+
+local function doubleCoins(coins: number): number
+	return coins
+end
+```
+
+`void` omits a return annotation. `int` / `float` / `double` → `number`. `bool` → `boolean`. Roblox types (`Player`, `Folder`) keep their name.
+
+If `void init()` exists, emit appends `init()` at the end of the file.
+
+## Locals and const
+
+Luau uses `local` for variables and `const` for constants. `const int` in C++ becomes `const` in Luau.
+
+```cpp
+int coins = 10;
+const int STARTING_COINS = 0;
+auto* folder = new Folder(player);
+```
+
+```luau
+local coins: number = 10
+const STARTING_COINS: number = 0
+local folder: Folder = Instance.new("Folder")
+folder.Parent = player
+```
+
+`auto` infers the type when the value is `new Class(...)` or `GetService<Service>()`.
+
+## Control flow
+
+```cpp
+if (player->FindFirstChild("leaderstats") != nullptr) {
+	return;
+} else {
+	print("ok");
+}
+
+while (true) {
+	print("tick");
+}
+
+for (auto* player : players->GetPlayers()) {
+	CreateLeaderstats(player);
+}
+```
+
+```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
+```
+
+The only `for` accepted today is **range-for**: `for (auto* x : list)`. C-style `for (int i = 0; i < n; i++)` is not supported yet.
+
+## Expressions
+
+| C++ | Luau |
+| --- | --- |
+| `nullptr` | `nil` |
+| `true` / `false` | `true` / `false` |
+| `!=` | `~=` |
+| `&&` | `and` |
+| `\|\|` | `or` |
+| `==` `+` `-` `*` `/` `<` `>` `<=` `>=` | same |
+| `"text"` | `"text"` |
+| `obj->Prop` | `obj.Prop` |
+| `obj->Method(a)` | `obj:Method(a)` if the method is a Roblox API |
+| `fn(a)` | `fn(a)` |
+| `signal.Connect(fn)` | `signal:Connect(fn)` |
+
+## `new` and services
+
+```cpp
+auto* coins = new IntValue(leaderstats);
+auto* players = GetService<Players>();
+```
+
+```luau
+local coins: IntValue = Instance.new("IntValue")
+coins.Parent = leaderstats
+local players: Players = game:GetService("Players")
+```
+
+The first argument of `new Class(parent)` becomes `.Parent`. With no argument: `Instance.new("Class")` only.
+
+## Not supported yet
+
+Custom C++ classes, generic templates besides `GetService<T>`, pointer arithmetic, `switch`, `std::`, overloading, macros (except skipping `#` lines).
+
+If you need one of those patterns, open an issue with the C++ and the expected Luau.