Getting started with Starminer mods

Modder setup

Start from the Starminer Framework template or one of the verified examples in the framework repository. Work against a copied Starminer install when testing mods locally.

powershell -ExecutionPolicy Bypass -File .\tools\Starminer.NewMod.ps1 -Name MyMod
powershell -ExecutionPolicy Bypass -File .\tools\Starminer.ValidateManifests.ps1 -Root ".\MyMod"

Runtime profile

The manager installs the pinned UE4SS runtime profile published by the framework repository and mirrored by this portal.

GET /api/v1/runtime/latest.json

Mods depend on starminer.framework; they do not bundle UE4SS.

Package contract

A Starminer mod package contains exactly one top-level mod directory or a root-level manifest.

ExampleMod/
  manifest.json
  Scripts/
    main.lua
  Binaries/
    Win64/
      ExampleMod.dll
  Paks/
    ExampleMod-WindowsNoEditor.pak
  Config/
    ExampleMod.ini

Manifest basics

The first portal API tracks the fields needed by the manager before install.

• Stable lowercase id matching ^[a-z0-9][a-z0-9._-]{1,63}$.
• Semantic version such as 0.1.0.
• Target Starminer game build.
• Entrypoints for ue4ss-lua, ue4ss-cpp, or pak.
• Explicit load ordering through loadAfter.

Dependencies

Framework-based Lua mods should declare the framework dependency in both manager metadata and the package manifest.

{
  "dependencies": {
    "starminer.framework": ">=0.5.5"
  },
  "loadAfter": [
    "starminer.framework"
  ]
}

Validation

Run local validation before uploading a ZIP to the portal.

powershell -ExecutionPolicy Bypass -File .\tools\Starminer.ValidateManifests.ps1 -Root ".\MyMod"

Portal validation will reject absolute paths, traversal paths, unexpected executable locations, mismatched manifest metadata, and archives that cannot be hashed safely.

Publish path

1. Create a free modder account when accounts are enabled.
2. Build a versioned ZIP from the framework template or an existing mod.
3. Upload the package and manifest metadata.
4. Wait for validation and review.
5. Published versions appear in the catalog and manager API.

Before the backend upload service is live, approved releases use the manual importer in the portal repo with a reviewed ZIP and sidecar metadata JSON.

.\tools\Import-ModRelease.ps1 -PackagePath ".\mod.zip" -MetadataPath ".\mod.release.json"

Troubleshooting

• If the manager says a mod is incompatible, compare the mod's targetGameBuild with the runtime profile build.
• If a mod needs a framework update, install the latest starminer.framework version before enabling the mod.
• If a package is rejected, check for absolute paths, .. traversal paths, missing manifest fields, or unexpected executable locations.
• If a mod does not load, confirm the manager enabled it in ILLSpace/Binaries/Win64/Mods/mods.txt.
• If UE4SS does not start, use the runtime profile to confirm the required files are in ILLSpace/Binaries/Win64.