rowork 0.1.0

package/templates/init/tsconfig.json.tmpl

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "downlevelIteration": true,
+    "jsx": "react",
+    "jsxFactory": "React.createElement",
+    "jsxFragmentFactory": "React.Fragment",
+    "module": "commonjs",
+    "moduleResolution": "Node",
+    "noLib": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleDetection": "force",
+    "strict": true,
+    "target": "ESNext",
+    "typeRoots": ["node_modules/@rbxts", "node_modules/@flamework"],
+
+    "rootDir": "src",
+    "outDir": "out",
+    "baseUrl": "src",
+    "incremental": true,
+    "tsBuildInfoFile": "out/tsconfig.tsbuildinfo",
+    "declaration": false,
+
+    "plugins": [{ "transform": "rbxts-transformer-flamework" }]
+  }
+}

package/templates/integrations/data-replication/DataReplicationService.ts.tmpl

@@ -0,0 +1,33 @@
+import { OnStart, Service } from "@flamework/core";
+import { DataEvents } from "{{ eventsImport }}";
+import { limit } from "{{ rateLimitImport }}";
+import { PlayerDataService } from "./PlayerDataService";
+
+const Events = DataEvents.createServer({
+	middleware: {
+		// A client asks for its data once when it starts: more than that is not normal.
+		dataRequested: [limit(5)],
+	},
+});
+
+/**
+ * Sends each player's data to their own client, and only theirs: one player
+ * never sees another's. The data is a copy for display: the server stays the
+ * only place that changes it (PlayerDataService.update).
+ */
+@Service()
+export class DataReplicationService implements OnStart {
+	constructor(private readonly playerData: PlayerDataService) {}
+
+	onStart(): void {
+		this.playerData.onLoaded((player, data) => Events.dataChanged.fire(player, data));
+		this.playerData.onChanged((player, data) => Events.dataChanged.fire(player, data));
+
+		// A client can start after its data loaded, and would never hear about it
+		// otherwise: it asks once when it is ready.
+		Events.dataRequested.connect((player) => {
+			const data = this.playerData.get(player);
+			if (data !== undefined) Events.dataChanged.fire(player, data);
+		});
+	}
+}

package/templates/integrations/data-replication/PlayerDataController.ts.tmpl

@@ -0,0 +1,40 @@
+import { Controller, OnStart } from "@flamework/core";
+import type { PlayerData } from "{{ dataImport }}";
+import { DataEvents } from "{{ eventsImport }}";
+
+const Events = DataEvents.createClient({});
+
+/**
+ * This player's data on their own screen, for interfaces to display. It is a
+ * read-only copy sent by the server: to change data, ask the server (a message,
+ * then PlayerDataService.update there). Changing it here changes nothing.
+ *
+ *   constructor(private readonly playerData: PlayerDataController) {}
+ *   this.playerData.onChanged((data) => label.Text = `${data.coins}`);
+ */
+@Controller()
+export class PlayerDataController implements OnStart {
+	private data: PlayerData | undefined;
+	private readonly listeners = new Array<(data: PlayerData) => void>();
+
+	onStart(): void {
+		Events.dataChanged.connect((data) => {
+			this.data = data;
+			for (const listener of this.listeners) task.spawn(listener, data);
+		});
+
+		// Ask the server for the data in case it loaded before this client was ready.
+		Events.dataRequested.fire();
+	}
+
+	/** The data, or undefined until the server has sent it. */
+	get(): Readonly<PlayerData> | undefined {
+		return this.data;
+	}
+
+	/** Runs each time the data changes, and right away if it is already known. */
+	onChanged(callback: (data: PlayerData) => void): void {
+		this.listeners.push(callback);
+		if (this.data !== undefined) task.spawn(callback, this.data);
+	}
+}

package/templates/integrations/data-replication/dataEvents.ts.tmpl

@@ -0,0 +1,21 @@
+import { Networking } from "@flamework/networking";
+import type { PlayerData } from "{{ dataImport }}";
+
+/**
+ * How a player's saved data reaches their own screen. Generated because both
+ * the player-data and the networking modules are installed.
+ *
+ * It has its own events on purpose, so your own src/shared/networking.ts stays
+ * yours: nothing here edits it.
+ */
+interface ClientToServerEvents {
+	/** The client has started and wants its data. It may have loaded before the client was ready. */
+	dataRequested(): void;
+}
+
+interface ServerToClientEvents {
+	/** The player's data: sent when it loads and each time it changes. */
+	dataChanged(data: PlayerData): void;
+}
+
+export const DataEvents = Networking.createEvent<ClientToServerEvents, ServerToClientEvents>();

package/templates/make/component.ts.tmpl

@@ -0,0 +1,8 @@
+import { BaseComponent, Component } from "@flamework/components";
+import { OnStart } from "@flamework/core";
+
+/** Attached by Flamework to every instance carrying the "{{ tag }}" CollectionService tag. */
+@Component({ tag: "{{ tag }}" })
+export class {{ className }} extends BaseComponent implements OnStart {
+	onStart(): void {}
+}

package/templates/make/controller.ts.tmpl

@@ -0,0 +1,6 @@
+import { Controller, OnStart } from "@flamework/core";
+
+@Controller()
+export class {{ className }} implements OnStart {
+	onStart(): void {}
+}

package/templates/make/event-handler.ts.tmpl

@@ -0,0 +1,22 @@
+import { OnStart, Service } from "@flamework/core";
+import { Events } from "{{ networkImport }}";
+{{ imports }}
+
+/**
+ * Runs on the server each time a player's client sends `{{ event }}`.
+ *
+ * Everything a client sends can be forged: a player can send any value, whenever
+ * they like, as often as they like. So decide HERE what happens and by how much,
+ * and never copy something you received into saved data.
+ */
+@Service()
+export class {{ className }} implements OnStart {
+	constructor({{ ctor }}) {}
+
+	onStart(): void {
+		Events.{{ event }}.connect((player) => {
+			// TODO: check that this player may do this now (cooldown, cost, distance...).
+{{ body }}
+		});
+	}
+}

package/templates/make/screen.tsx.tmpl

@@ -0,0 +1,35 @@
+import React from "@rbxts/react";
+
+/**
+ * The {{ name }} screen.
+ *
+ * A screen is a ScreenGui: one full-screen layer of your interface. `App` shows it
+ * (Rowork listed it there for you), and each screen is separate so it can be shown,
+ * hidden and ordered on its own.
+ *
+ * - `key` is the name the ScreenGui gets in the game (PlayerGui > {{ name }}), so scripts can find it.
+ * - `ResetOnSpawn={false}` keeps it when the character respawns.
+ * - `DisplayOrder` (add it to the ScreenGui) puts a screen in front of another: higher is in front.
+ * - `Enabled` shows or hides the whole screen, e.g. from a `useState` in this component.
+ *
+ * Add elements with `rowork make:ui <name> --in {{ name }}`, or write them between the frame tags.
+ */
+export function {{ className }}() {
+	return (
+		<screengui key="{{ name }}" ResetOnSpawn={false} ZIndexBehavior={Enum.ZIndexBehavior.Sibling}>
+			<frame Size={UDim2.fromScale(1, 1)} BackgroundTransparency={1}>
+				{/* A placeholder, so you can see the screen work: delete it once you add your own. */}
+				<textlabel
+					Size={UDim2.fromOffset(300, 50)}
+					Position={UDim2.fromScale(0.5, 0.1)}
+					AnchorPoint={new Vector2(0.5, 0)}
+					BackgroundColor3={Color3.fromRGB(30, 30, 35)}
+					TextColor3={Color3.fromRGB(255, 255, 255)}
+					Text="{{ name }}"
+					TextScaled
+				/>
+				{{ elementsMarker }}
+			</frame>
+		</screengui>
+	);
+}

package/templates/make/service.ts.tmpl

@@ -0,0 +1,6 @@
+import { OnStart, Service } from "@flamework/core";
+{{ imports }}
+@Service()
+export class {{ className }} implements OnStart {
+{{ members }}	onStart(): void {}
+}

package/templates/make/stat-service.ts.tmpl

@@ -0,0 +1,26 @@
+import { Service } from "@flamework/core";
+import { PlayerDataService } from "./PlayerDataService";
+
+/**
+ * Reads and changes the `{{ name }}` value that is saved for each player.
+ * The value itself lives in PlayerData (it was added there for you), so it is
+ * saved and loaded with everything else: nothing more to wire.
+ */
+@Service()
+export class {{ className }} {
+	constructor(private readonly playerData: PlayerDataService) {}
+
+	/** The player's `{{ name }}`, or undefined while their data is still loading. */
+	get(player: Player): {{ type }} | undefined {
+		const data = this.playerData.get(player);
+		return data === undefined ? undefined : data.{{ name }};
+	}
+
+	/** Sets the player's `{{ name }}`. */
+	set(player: Player, value: {{ type }}): void {
+		this.playerData.update(player, (data) => {
+			data.{{ name }} = value;
+			return data;
+		});
+	}
+{{ extra }}}

package/templates/make/ui-button.tsx.tmpl

@@ -0,0 +1,22 @@
+import React from "@rbxts/react";
+
+interface {{ name }}Props {
+	text?: string;
+	onClick?: () => void;
+}
+
+/**
+ * A button. `text` is what it says and `onClick` runs when it is pressed. Both are
+ * optional so `<{{ name }} />` works as soon as it is placed; a game rule never goes
+ * here (the client can be tampered with): send an event and let the server decide.
+ */
+export function {{ name }}({ text = "{{ name }}", onClick }: {{ name }}Props) {
+	return (
+		<textbutton
+			Size={UDim2.fromOffset(200, 50)}
+			Text={text}
+			TextScaled
+			Event={{ Activated: () => onClick?.() }}
+		/>
+	);
+}

package/templates/make/ui-image.tsx.tmpl

@@ -0,0 +1,11 @@
+import React from "@rbxts/react";
+
+interface {{ name }}Props {
+	/** An image id, e.g. `Assets.logo` from `rowork assets` (see src/shared/assets.ts). */
+	image?: string;
+}
+
+/** An image. Upload files with `rowork assets` and pass `Assets.<name>` as `image`. */
+export function {{ name }}({ image = "" }: {{ name }}Props) {
+	return <imagelabel Image={image} Size={UDim2.fromOffset(120, 120)} BackgroundTransparency={1} />;
+}

package/templates/make/ui-label.tsx.tmpl

@@ -0,0 +1,18 @@
+import React from "@rbxts/react";
+
+interface {{ name }}Props {
+	text?: string;
+}
+
+/** A piece of text. `text` is optional so `<{{ name }} />` works as soon as it is placed. */
+export function {{ name }}({ text = "{{ name }}" }: {{ name }}Props) {
+	return (
+		<textlabel
+			Size={UDim2.fromOffset(200, 30)}
+			BackgroundTransparency={1}
+			TextColor3={Color3.fromRGB(255, 255, 255)}
+			Text={text}
+			TextScaled
+		/>
+	);
+}

package/templates/make/ui-panel.tsx.tmpl

@@ -0,0 +1,33 @@
+import React from "@rbxts/react";
+
+interface {{ name }}Props {
+	title?: string;
+	children?: React.ReactNode;
+}
+
+/**
+ * A rounded panel with a title. Whatever you put between `<{{ name }}>` and `</{{ name }}>`
+ * is stacked below the title (that is what `children` is), so a panel can hold anything.
+ */
+export function {{ name }}({ title = "{{ name }}", children }: {{ name }}Props) {
+	return (
+		<frame Size={UDim2.fromOffset(300, 200)} BackgroundColor3={Color3.fromRGB(30, 30, 35)}>
+			<uicorner CornerRadius={new UDim(0, 8)} />
+			<uipadding
+				PaddingTop={new UDim(0, 10)}
+				PaddingBottom={new UDim(0, 10)}
+				PaddingLeft={new UDim(0, 10)}
+				PaddingRight={new UDim(0, 10)}
+			/>
+			<uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />
+			<textlabel
+				Size={new UDim2(1, 0, 0, 30)}
+				BackgroundTransparency={1}
+				TextColor3={Color3.fromRGB(255, 255, 255)}
+				Text={title}
+				TextScaled
+			/>
+			{children}
+		</frame>
+	);
+}

package/templates/make/ui-story.tsx.tmpl

@@ -0,0 +1,13 @@
+import React from "@rbxts/react";
+import ReactRoblox from "@rbxts/react-roblox";
+import { CreateReactStory } from "@rbxts/ui-labs";
+import { {{ name }} } from "./{{ name }}";
+
+/**
+ * A story shows one component on its own, inside Studio, without running the game
+ * (open the UI Labs plugin). `controls` become fields you can change live.
+ */
+export = CreateReactStory(
+	{ react: React, reactRoblox: ReactRoblox, controls: {{ controls }} },
+	(props) => <{{ name }} {{ binding }} />,
+);

package/templates/modules/format/prettierignore.tmpl

@@ -0,0 +1,9 @@
+# Build output and generated files: never formatted by hand.
+out
+include
+node_modules
+sourcemap.json
+flamework.build
+package-lock.json
+*.rbxl
+*.rbxlx

package/templates/modules/format/prettierrc.json.tmpl

@@ -0,0 +1,4 @@
+{
+	"useTabs": true,
+	"printWidth": 100
+}

package/templates/modules/leaderstats/LeaderstatsService.ts.tmpl

@@ -0,0 +1,69 @@
+import { OnStart, Service } from "@flamework/core";
+import type { PlayerData } from "{{ dataImport }}";
+import { PlayerDataService } from "./PlayerDataService";
+
+const Players = game.GetService("Players");
+
+/**
+ * The PlayerData fields shown in the in-game leaderboard, in this order.
+ * Add a field name here and it appears for every player. Roblox displays
+ * numbers, text and yes/no values.
+ */
+const SHOWN: ReadonlyArray<keyof PlayerData> = [{{ shown }}];
+
+/**
+ * Mirrors player data into Roblox's leaderboard.
+ *
+ * Roblox shows any Folder named "leaderstats" under a Player, with one value
+ * object per column. This service builds it when a player's data has loaded and
+ * keeps it in sync when the data changes through PlayerDataService.update.
+ * The leaderboard is only a display: never read it back as the source of truth.
+ */
+@Service()
+export class LeaderstatsService implements OnStart {
+	constructor(private readonly playerData: PlayerDataService) {}
+
+	onStart(): void {
+		this.playerData.onLoaded((player, data) => this.create(player, data));
+		this.playerData.onChanged((player, data) => this.refresh(player, data));
+
+		// Players whose data finished loading before this service started.
+		for (const player of Players.GetPlayers()) {
+			const data = this.playerData.get(player);
+			if (data !== undefined) this.create(player, data);
+		}
+	}
+
+	private create(player: Player, data: Readonly<PlayerData>): void {
+		if (player.FindFirstChild("leaderstats") !== undefined) return;
+
+		const folder = new Instance("Folder");
+		folder.Name = "leaderstats";
+
+		for (const field of SHOWN) {
+			const value = data[field];
+			let stat: NumberValue | StringValue | BoolValue;
+
+			if (typeIs(value, "number")) stat = new Instance("NumberValue");
+			else if (typeIs(value, "boolean")) stat = new Instance("BoolValue");
+			else stat = new Instance("StringValue");
+
+			stat.Name = field;
+			stat.Value = value as never;
+			stat.Parent = folder;
+		}
+
+		folder.Parent = player;
+	}
+
+	private refresh(player: Player, data: Readonly<PlayerData>): void {
+		const folder = player.FindFirstChild("leaderstats");
+		if (folder === undefined) return;
+
+		for (const field of SHOWN) {
+			const stat = folder.FindFirstChild(field);
+			if (stat === undefined || !stat.IsA("ValueBase")) continue;
+			(stat as unknown as { Value: unknown }).Value = data[field];
+		}
+	}
+}

package/templates/modules/lint/eslint.config.mjs.tmpl

@@ -0,0 +1,17 @@
+import roblox from "eslint-plugin-roblox-ts";
+
+/**
+ * ESLint with the official roblox-ts rules.
+ *
+ * roblox-ts turns TypeScript into Luau, and Luau cannot do everything
+ * TypeScript can. These rules catch what the compiler would reject, or worse,
+ * accept and get wrong at runtime: `any`, `null` (Luau has `nil`, use
+ * `undefined`), unsupported operators, and so on. Run it with `npm run lint`.
+ *
+ * To turn a rule off or change its level, add an entry after the recommended set:
+ *   { rules: { "roblox-ts/no-any": "warn" } }
+ */
+export default [
+	{ ignores: ["out/**", "include/**", "node_modules/**"] },
+	roblox.configs.recommended,
+];

package/templates/modules/networking/client-network.ts.tmpl

@@ -0,0 +1,9 @@
+import { GlobalEvents } from "{{ networkingImport }}";
+
+/**
+ * The client's side of every event.
+ *
+ *   Events.buyItem.fire(itemId, amount);                  // send to the server
+ *   Events.itemBought.connect((itemId) => { ... });       // the server sent one
+ */
+export const Events = GlobalEvents.createClient({});

package/templates/modules/networking/networking.ts.tmpl

@@ -0,0 +1,22 @@
+import { Networking } from "@flamework/networking";
+
+/**
+ * Every message between client and server, described once, with types.
+ * Roblox RemoteEvents are created and wired for you: nothing to set up by hand.
+ *
+ * To add an event, add a line in the right interface below:
+ *
+ *   buyItem(itemId: string, amount: number): void;
+ *
+ * Events the client sends TO the server:
+ */
+interface ClientToServerEvents {
+{{ toServer }}
+}
+
+/** Events the server sends TO the client(s): */
+interface ServerToClientEvents {
+{{ toClient }}
+}
+
+export const GlobalEvents = Networking.createEvent<ClientToServerEvents, ServerToClientEvents>();

package/templates/modules/networking/rate-limit.ts.tmpl

@@ -0,0 +1,52 @@
+import type { Networking } from "@flamework/networking";
+
+const Players = game.GetService("Players");
+
+/**
+ * How many times ONE player may send the SAME event per second before the extra
+ * ones are ignored. Generous on purpose: normal play never gets near it, a script
+ * hammering the server does. Lower it for events that should be rare.
+ */
+export const DEFAULT_PER_SECOND = 30;
+
+/**
+ * Anti-spam for an event the client sends.
+ *
+ * A client is not trusted: a cheater can fire any event as fast as their computer
+ * allows, and every call runs your server code. Without a limit, one player can
+ * freeze the server for everyone. Add it to an event in `network.ts`:
+ *
+ *   buyItem: [limit()],       // the default
+ *   openChest: [limit(2)],    // at most twice a second
+ *
+ * Extra messages are dropped, and a warning tells you once per second so the cause
+ * is visible in your logs.
+ */
+export function limit<I extends readonly unknown[]>(
+	perSecond = DEFAULT_PER_SECOND,
+): Networking.EventMiddleware<I> {
+	return (processNext, event) => {
+		const windows = new Map<Player, { start: number; count: number }>();
+		Players.PlayerRemoving.Connect((player) => windows.delete(player));
+
+		return (player, ...args) => {
+			// Only the server receives from clients, so a player is always there.
+			if (player === undefined) return processNext(player, ...args);
+
+			const now = os.clock();
+			const window = windows.get(player);
+			if (window === undefined || now - window.start >= 1) {
+				windows.set(player, { start: now, count: 1 });
+				return processNext(player, ...args);
+			}
+
+			window.count += 1;
+			if (window.count <= perSecond) return processNext(player, ...args);
+
+			// Warn once per window, not once per dropped message: that would be spam too.
+			if (window.count === perSecond + 1) {
+				warn(`[network] ${player.Name} sends "${event.name}" too fast: extra messages are ignored`);
+			}
+		};
+	};
+}

package/templates/modules/networking/server-network.ts.tmpl

@@ -0,0 +1,20 @@
+import { GlobalEvents } from "{{ networkingImport }}";
+import { limit } from "{{ rateLimitImport }}";
+
+/**
+ * The server's side of every event.
+ *
+ *   Events.buyItem.connect((player, itemId, amount) => { ... });   // the client sent one
+ *   Events.itemBought.fire(player, itemId);                          // send to one player
+ *   Events.itemBought.broadcast(itemId);                             // send to everyone
+ *
+ * The player who sent an event is always the first argument: clients cannot lie
+ * about who they are, so never take a player from the arguments.
+ */
+export const Events = GlobalEvents.createServer({
+	middleware: {
+		// Every event the client sends is limited per player, so one player cannot flood
+		// the server. Rowork adds a line here for each new event. Pass a number to change
+		// one: limit(2) allows two a second. See rateLimit.ts.{{ entries }}
+	},
+});

package/templates/modules/player-data/PlayerData.ts.tmpl

@@ -0,0 +1,15 @@
+/**
+ * Everything that is saved for one player.
+ *
+ * To save something new, add it in TWO places in this file: the interface below
+ * and DEFAULT_PLAYER_DATA. TypeScript refuses to compile if you forget one.
+ * Players who already have a save get the default the next time they join.
+ */
+export interface PlayerData {
+{{ interfaceFields }}
+}
+
+/** What a brand-new player starts with. */
+export const DEFAULT_PLAYER_DATA: PlayerData = {
+{{ defaultFields }}
+};