Development

Development

This page describes the OpenLuaTools repository layout and useful notes for contributors.

Repository layout

OpenSteamToolPlugin/
├─ .millennium/Dist/        # Built Millennium frontend bridge files
├─ backend/                 # Lua backend modules
│  ├─ data/                 # Default settings/data
│  ├─ locales/              # Translation files
│  ├─ settings/             # Settings manager/options
│  ├─ api.json              # Default API source definitions
│  ├─ main.lua              # Plugin lifecycle and exported API methods
│  ├─ downloads.lua         # Download, extraction, and Lua install flow
│  ├─ fixes.lua             # Helper/fix archive check/apply flow
│  ├─ paths.lua             # Plugin/backend/public path helpers
│  ├─ safety.lua            # URL/path/archive safety validation
│  └─ steam_utils.lua       # Steam/OpenSteamTool path helpers
├─ public/                  # Webkit assets, icon, CSS, themes
├─ scripts/                 # Contributor/dev scripts
├─ CHANGELOG.md
├─ plugin.json
└─ readme.md

Plugin metadata

plugin.json defines:

{
  "name": "openluatools",
  "common_name": "OpenLuaTools",
  "description": "OpenLuaTools Millennium plugin for OpenSteamTool.",
  "version": "1.0.0",
  "backendType": "lua",
  "include": ["public"]
}

Backend lifecycle

backend/main.lua returns a lifecycle table with:

• on_load
• on_unload
• on_frontend_loaded

On load, the plugin:

1. Logs startup.
2. Detects the Steam install path.
3. Ensures the temporary download directory exists.
4. Initializes settings.
5. Applies any pending update state.
6. Copies public webkit files.
7. Injects browser CSS and JS.
8. Initializes API sources.
9. Calls millennium.ready().

Exported backend methods

The backend exposes methods for:

• Plugin directory detection.
• API initialization and source management.
• Update checks and Steam restart.
• Lua script presence checks.
• Lua script install status.
• Lua script deletion.
• API availability checks.
• Icon data lookup.
• Installed script listing.
• Game install path lookup.
• Opening game folders and external URLs.
• Settings schema/value retrieval.
• Settings changes.
• Locale and translation lookup.
• Theme lookup.

Most exported methods return JSON-encoded strings so the frontend receives predictable data through the Millennium Lua bridge.

Download/install flow

The Lua install flow is handled in backend/downloads.lua.

High-level flow:

1. Select a trusted configured source.
2. Start an async download.
3. Extract to a temporary plugin directory.
4. Validate every extracted file path.
5. Copy valid manifests into Steam's depotcache.
6. Copy the expected <appid>.lua file into <Steam>/config/lua.
7. Preserve setManifestid(...) lines.
8. Clean temporary files.

Safety rules to preserve

Do not weaken these checks:

• HTTP/HTTPS-only external URLs.
• Unsafe character rejection for URLs and paths.
• Archive path traversal rejection.
• Destination path containment checks.
• App ID based Lua filename validation.
• Numeric manifest filename validation.
• Temporary extraction before copying.

Development install

For development, place the repository folder directly in the Millennium plugins directory or use a symbolic link.

After frontend/public changes, a Steam UI reload may be enough. After backend Lua changes, restart Steam.

Suggested commit checklist

Before committing:

• Confirm plugin.json is valid JSON.
• Confirm the plugin loads in Millennium.
• Test enabling and disabling the plugin.
• Test settings load and save.
• Test locale validation if translations changed.
• Test downloads only with files you are allowed to use.
• Check logs for Lua errors.
• Update CHANGELOG.md for user-facing changes.