Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nebula-Modmakers/Nebula-Launcher/llms.txt

Use this file to discover all available pages before exploring further.

NPKG is the package format used by Nebula Launcher to distribute and install mods. An .npkg file is a standard ZIP archive containing a manifest.json at the root and a payload/ directory holding the actual mod files. Packages are obtained either from the integrated mod store — where Nebula downloads, verifies, and installs them automatically — or by importing a compatible ZIP or DLL file manually. In both cases NpkgInstaller validates the manifest, verifies every file’s SHA-256 hash, and performs a transactional install with automatic rollback on failure, so a broken package cannot leave the active profile in a partial state.

​
Package structure

An NPKG file is a regular ZIP archive. It must contain exactly two top-level items: the manifest and the declared payload files. No other entries are permitted. 
my-mod-1.0.0.npkg  (ZIP)
├── manifest.json
└── payload/
    └── MyMod.dll   (or other declared files)
Directory entries inside the ZIP are allowed but are not installed. Only files explicitly listed in manifest.json under install.files are extracted and copied into the profile.

​
manifest.json

The manifest is a UTF-8 JSON file at the ZIP root. All required fields must be present and non-empty; optional fields may be omitted. NpkgInstaller.validateManifest rejects any manifest that fails these constraints.

​
Top-level fields

​
format
string
required
Must be exactly "nebula-package". Any other value causes the package to be rejected as an unsupported format.
​
formatVersion
integer
required
Must be 1. Future format revisions will use a higher value.
​
id
string
required
The package identifier. When installed from the mod store, this must match the packageId field in the catalog entry exactly.
​
version
string
required
The package version string. When installed from the mod store, this must match the version field in the catalog entry exactly.
​
licenses
array of strings
required
One or more SPDX license identifiers (e.g. ["MIT"], ["GPL-3.0-only", "MIT"]). Each identifier must match the pattern [A-Za-z0-9.+-]{1,128}. The array must contain at least one entry and no more than 32. When installed from the mod store, the set of identifiers must match the catalog exactly.
​
githubRepos
array of objects
Optional list of GitHub repository references attributed to this package. Each object must have:
  • name (string) — display name of the repository
  • url (string) — a valid https://github.com/ URL
When installed from the mod store, the set of repositories must match the catalog exactly.
​
licenseComponents
object
Optional map from each license identifier in licenses to an array of attributed component names (strings). When present, every identifier in licenses must have a corresponding entry with at least one non-empty component name and no more than 64.
​
platform
object
required
Declares the platform constraints for this package. See Platform object below.
​
install
object
required
Declares the installation target and the list of files to install. See Install object below.

​
Platform object

The platform object inside the manifest specifies every constraint that Nebula checks before allowing installation to proceed. All five fields are required.
​
platform.os
string
required
Must be "android".
​
platform.architecture
string
required
Must be "arm64-v8a". Nebula only runs on 64-bit ARM devices.
​
platform.runtime
string
required
Must be "fusioncore". Identifies that this package requires the FusionCore IL2CPP mod-loading runtime.
​
platform.gamePackage
string
required
Must be "com.innersloth.spacemafia" (the Among Us Android package name).
​
platform.gameVersion
string
required
Must be "2026.6.5" — the exact Among Us package version name required by the current Nebula build (version code 7045, in-game display 17.4a).

​
Install object

​
install.targetRoot
string
required
Must be "activeProfile". Instructs the installer to write files relative to the currently active profile’s root directory.
​
install.files
array of objects
required
List of file mappings. Must contain at least one entry and no more than 256. Each entry describes one file to be extracted and installed:
  • source (string, required) — path inside the ZIP. Must start with payload/ and must not contain path traversal sequences.
  • destination (string, required) — target path relative to the profile root. Must start with plugins/ and must not escape the profile directory.
  • size (long, required) — exact uncompressed byte size of the file. The installer checks ZipEntry.getSize() before extracting and rejects any entry whose size does not match.
  • sha256 (string, required) — lowercase hexadecimal SHA-256 hash of the uncompressed file contents (64 characters, [0-9a-f]{64}). Verified after extraction; mismatches abort the install with rollback.

​
Security constraints

NpkgInstaller enforces the following hard limits and integrity rules before and during installation. Any violation aborts the operation and rolls back any files that were already written.

Size limits

  • Compressed package: ≤ 512 MB (checked during download and again at install time)
  • Total uncompressed payload: ≤ 768 MB (sum of all size values in install.files)
  • Maximum files per package: 256
  • Manifest file size: ≤ 1 MB

Path safety

  • All destination paths must start with plugins/ and must not end with /
  • Canonical path resolution confirms no destination escapes the profile root
  • No path traversal sequences (../, /..) are permitted in either source or destination
  • Paths must not start with / or contain \ or :

Archive integrity

  • No undeclared entries in the ZIP (only manifest.json and declared payload/ files are allowed)
  • Duplicate archive entry names are rejected
  • Each declared source must appear exactly once in install.files
  • Case-insensitive duplicate check on destination paths prevents collisions on case-insensitive file systems

Hash verification

  • Every payload file is streamed through SHA-256 during extraction
  • Computed hash must match the sha256 field exactly (lowercase hex)
  • Extracted byte count must equal the declared size exactly
  • Download from the mod store also verifies the whole-package SHA-256 against the catalog before installation begins
The installer performs a transactional install: existing files are backed up before being overwritten, and if any step fails the original files are restored. However, rollback operates on the files that were touched during the current install run only. Always test packages against a non-essential profile first.

​
Complete manifest.json example

manifest.json
{
  "format": "nebula-package",
  "formatVersion": 1,
  "id": "com.example.mymod",
  "version": "1.0.0",
  "licenses": ["MIT"],
  "platform": {
    "os": "android",
    "architecture": "arm64-v8a",
    "runtime": "fusioncore",
    "gamePackage": "com.innersloth.spacemafia",
    "gameVersion": "2026.6.5"
  },
  "install": {
    "targetRoot": "activeProfile",
    "files": [
      {
        "source": "payload/MyMod.dll",
        "destination": "plugins/MyMod.dll",
        "size": 204800,
        "sha256": "abc123def456abc123def456abc123def456abc123def456abc123def456abcd"
      }
    ]
  }
}
Generate the sha256 and size values with sha256sum on Linux/macOS, or Get-FileHash (SHA256) and (Get-Item ...).Length in PowerShell. The hash must be the hash of the uncompressed file content — not the hash of the ZIP entry.

Build docs developers (and LLMs) love

Get started for freeTalk to us