workspace-detector/README.md

workspace-detector

A command-line tool for analyzing Roblox .rbxm(x) model files to identify workspaces and detect hidden places embedded within them.

Overview

This tool works to detect Roblox workspaces within .rbxm(x) model files, which could potentially contain stolen/lost places. It runs on the Lune runtime environment.

Project Structure

• detector.luau: Main entrypoint
• lib/cli.luau: CLI argument parsing and usage
• lib/core.luau: Core detection logic (workspace scanning, file analysis)
• lib/fileproc.luau: File and directory processing
• tests/: Test models for validation
  • containsworkspace/: Models that should be detected as containing workspaces
  • doesntcontainworkspace/: Models that should NOT be detected as containing workspaces
  • zlibCompressed/: Models compressed with zlib
  • binaryFiles/: Binary or extensionless test files

Installation

Prerequisites

Install the Lune runtime using rokit

Setup

Clone or download this repository and ensure all required libraries are installed:

git clone https://github.com/filoxen/workspace-detector.git
cd workspace-detector
rokit install

Usage

Basic Usage

lune run detector path/to/your/model.rbxm(x)

Options

Directory scan (recursive):

lune run detector.lua --directory /path/to/your/directory/with/models

Output list of files containing workspaces:

lune run detector.lua --output /path/to/your/output/file.txt

Process non-extensioned files (i.e no filetype extension / differing extension from .rbxm)

lune run detector.lua --force-binary-read /path/to/your/model.variantfile

Print all instance names while scanning:

lune run detector.lua --print-instance-names /path/to/your/model.rbxm

Decompress zlib-compressed files before scanning:

lune run detector.lua --zlib-decompress /path/to/your/model.rbxm

Limitations

• Requires valid .rbxm files (corrupted/invalid/different versioned files may cause errors)

Contributing

Contributions are welcome. Please ensure new features include documentation.