@jaeymo/toybox 1.0.0

package/README.md

@@ -0,0 +1 @@
+# toybox

package/default.project.json

@@ -0,0 +1,34 @@
+{
+    "name": "sometest",
+    "tree": {
+        "$className": "DataModel",
+        "ReplicatedStorage": {
+            "FilesHere": {
+                "$className": "Folder"
+            },
+            "Asset": {
+                "$className": "Folder",
+                "Models": {
+                    "$className": "Folder",
+                    "AnotherModel": {
+                        "$className": "Model",
+                        "SomePartName": {
+                            "$className": "Part"
+                        },
+                        "PrettyPrincess": {
+                            "$className": "Model"
+                        }
+                    }
+                },
+                "SomeModelName": {
+                    "$className": "Model"
+                }
+            }
+        },
+        "ServerScriptService": {
+            "files": {
+                "$className": "Folder"
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@jaeymo/toybox",
+    "version": "1.0.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "Toybox scans a Roblox hierarchy and produces a Rojo mapping so all of your assets are statically represented",
+    "homepage": "https://github.com/jaeymo/toybox#readme",
+    "bugs": {
+        "url": "https://github.com/jaeymo/toybox/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/jaeymo/toybox.git"
+    },
+    "license": "MIT",
+    "author": "Jaeymo",
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "build": "tsc",
+        "dev": "ts-node src/cli.ts",
+        "clean": "rimraf dist"
+    },
+    "dependencies": {
+        "commander": "^14.0.3",
+        "fast-xml-parser": "^5.3.6",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^25.2.3",
+        "eslint": "^10.0.0",
+        "globals": "^17.3.0",
+        "rimraf": "^6.1.3",
+        "typescript-eslint": "^8.56.0"
+    }
+}

package/src/cli.ts

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { generateMapping } from "./generator.js";
+
+const program = new Command();
+
+program
+    .name("toybox")
+    .description("Generate rojo mappings from a Roblox directory")
+    .version("1.0.0");
+
+program
+    .command("generate")
+    .requiredOption("-i, --input <path>", "Input roblox directory")
+    .option("-f, --folder <name>", "Folder inside Roblox to map", "Asset")
+    .requiredOption("-o, --output <path>", "Path to .project.json")
+    .action((options) => {
+        generateMapping(options.input, options.output, options.folder);
+    });
+
+program.parse(process.argv);

package/src/generator.ts

@@ -0,0 +1,123 @@
+import fs from "fs";
+import { XMLParser } from "fast-xml-parser";
+
+interface AssetNode {
+    name: string;
+    className: string;
+    children?: Record<string, AssetNode>;
+}
+
+function getItemName(item: any): string | null {
+    if (!item.Properties || !item.Properties.string) return null;
+
+    const strings = Array.isArray(item.Properties.string)
+        ? item.Properties.string
+        : [item.Properties.string];
+
+    for (const str of strings) {
+        if (str.name === "Name") {
+            if (typeof str === "string") return str;
+            if ("#text" in str) return str["#text"];
+        }
+    }
+
+    return null;
+}
+
+function findFolderByName(item: any, name: string): any | null {
+    const itemName = getItemName(item);
+    if (itemName === name) return item;
+
+    const children = item.Item
+        ? Array.isArray(item.Item)
+            ? item.Item
+            : [item.Item]
+        : [];
+    for (const child of children) {
+        const found = findFolderByName(child, name);
+        if (found) return found;
+    }
+
+    return null;
+}
+
+function traverse(item: any): AssetNode {
+    const name = getItemName(item) || "Unnamed";
+    const node: AssetNode = {
+        name,
+        className: item.class,
+        children: {},
+    };
+
+    const children = item.Item
+        ? Array.isArray(item.Item)
+            ? item.Item
+            : [item.Item]
+        : [];
+    for (const child of children) {
+        const childNode = traverse(child);
+        node.children![childNode.name] = childNode;
+    }
+
+    return node;
+}
+
+function toRojo(node: AssetNode): Record<string, any> {
+    const result: Record<string, any> = { $className: node.className };
+    if (node.children && Object.keys(node.children).length > 0) {
+        for (const [name, child] of Object.entries(node.children)) {
+            result[name] = toRojo(child as AssetNode);
+        }
+    }
+    return result;
+}
+
+export function buildTreeFromRbxlx(
+    filePath: string,
+    rootName: string,
+): Record<string, any> {
+    const xmlData = fs.readFileSync(filePath, "utf-8");
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "",
+    });
+    const jsonObj = parser.parse(xmlData);
+
+    const items = Array.isArray(jsonObj.roblox.Item)
+        ? jsonObj.roblox.Item
+        : [jsonObj.roblox.Item];
+    const rootItem = findFolderByName({ Item: items }, rootName);
+    if (!rootItem) throw new Error(`Folder '${rootName}' not found in .rbxlx`);
+
+    const rootNode = traverse(rootItem);
+    return { [rootNode.name]: toRojo(rootNode) };
+}
+
+export function generateMapping(
+    input: string,
+    rojoPath: string,
+    folderName: string,
+) {
+    if (!fs.existsSync(input)) {
+        console.error("Input file does not exist");
+        process.exit(1);
+    }
+
+    if (!fs.existsSync(rojoPath)) {
+        console.error("Rojo project file does not exist");
+        process.exit(1);
+    }
+
+    const project = JSON.parse(fs.readFileSync(rojoPath, "utf-8"));
+    if (!project.tree || !project.tree.ReplicatedStorage) {
+        console.error(
+            "Invalid Rojo project structure (is there a ReplicatedStorage?)",
+        );
+        process.exit(1);
+    }
+
+    const mapping = buildTreeFromRbxlx(input, folderName);
+    project.tree.ReplicatedStorage[folderName] = mapping[folderName];
+    fs.writeFileSync(rojoPath, JSON.stringify(project, null, 4));
+    console.log(`Mapping generated for '${folderName}'`);
+}

package/tsconfig.json

@@ -0,0 +1,45 @@
+{
+    // Visit https://aka.ms/tsconfig to read more about this file
+    "compilerOptions": {
+        // File Layout
+        "rootDir": "./src",
+        "outDir": "./dist",
+
+        // Environment Settings
+        // See also https://aka.ms/tsconfig/module
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "target": "esnext",
+        "types": ["node"],
+        // For nodejs:
+        // "lib": ["esnext"],
+        // "types": ["node"],
+        // and npm install -D @types/node
+
+        // Other Outputs
+        "sourceMap": true,
+        "declaration": true,
+        "declarationMap": true,
+
+        // Stricter Typechecking Options
+        "noUncheckedIndexedAccess": true,
+        "exactOptionalPropertyTypes": true,
+
+        // Style Options
+        // "noImplicitReturns": true,
+        // "noImplicitOverride": true,
+        // "noUnusedLocals": true,
+        // "noUnusedParameters": true,
+        // "noFallthroughCasesInSwitch": true,
+        // "noPropertyAccessFromIndexSignature": true,
+
+        // Recommended Options
+        "strict": true,
+        "jsx": "react-jsx",
+        "verbatimModuleSyntax": true,
+        "isolatedModules": true,
+        "noUncheckedSideEffectImports": true,
+        "moduleDetection": "force",
+        "skipLibCheck": true
+    }
+}