PUKEY Mods / docs
Mod packages and catalogue contract
The manager accepts the official repository catalogue and independent community ZIPs or mod folders. Importing inspects data only: it never runs installers, Lua, DLLs, build scripts or repository commands. Package validation checks structure and settings declarations. It cannot establish runtime safety, native ABI compatibility or game compatibility.
Public package manifest
Put pukey-mod.json at each mod root. A ZIP can contain one mod directly, a common
wrapper folder, or several mod roots such as Mods/First/ and Mods/Second/.
Overlapping mod roots, case-colliding paths, symlinks/reparse points, traversal paths,
missing declared files and ambiguous native entrypoints are rejected. Preserve the
actual spelling of paths, including Scripts/main.lua and native DLL names.
{
"schema_version": 1,
"id": "ExampleLua",
"name": "Example Lua",
"version": "1.0.0",
"description": "Explain what the mod changes.",
"controls": "F12: toggle",
"author": "Your name",
"homepage": "https://example.com/mod",
"requires": ["A working UE4SS installation for your game"],
"files": ["Scripts/main.lua", "README.md"],
"entrypoints": [{"type": "lua", "path": "Scripts/main.lua"}],
"default_files": ["settings.lua"],
"settings": [
{
"key": "Mode", "label": "Mode", "type": "enum", "default": "idle",
"options": ["idle", "always"],
"description": "Choose when this feature runs.",
"option_descriptions": {"idle": "Run while idle.", "always": "Run continuously."}
}
],
"configuration": [
{"file": "settings.lua", "format": "lua", "bindings": {"Mode": {"key": "Mode"}}}
]
}
schema_version must be integer 1. id, name, version, description and
files are required. IDs start with a letter, followed by letters, digits, _ or
-, at most 64 characters; they must be unique ignoring case within a source.
description is plain text of at most 4096 characters. controls defaults to an empty string. settings and default_files default to
empty arrays. author and homepage are optional strings up to 4096 characters;
homepage, when nonempty, uses HTTP or HTTPS. requires is an optional array of
strings, each at most 4096 characters; these are informational prerequisites, not
an automatic dependency installer. Unknown schema features are rejected.
entrypoints is a nonempty list of { "type": "lua" | "native", "path": "..." }
objects. Every path must also appear in files, with a .lua or .dll extension
matching its type. When omitted in schema 1, the entrypoint is Scripts/main.lua.
A native package normally uses dlls/main.dll; UE4SS also supports
dlls/<mod-folder>.dll. Match the UE4SS architecture, SDK, C++ runtime and build
configuration when building native code. See the official
installation layout
and C++ authoring guide.
The manager does not build DLLs or verify these prerequisites.
Program files, defaults and personal data
files contains all owned program payloads, relative to the mod root. Every listed
file must be present in the package. Do not list activation marker enabled.txt or
personal settings.lua/settings.json as program files. Program updates compare
payload contents as well as the mod version. Increment the version when changing
program behavior.
default_files contains initial configuration seeds. They must exist in the
package, be disjoint from program files and may not contain enabled.txt. A seed
is copied only if its destination is missing. Existing files remain personal data
and survive program updates and removal. A configuration target is also personal
data, whether or not a seed exists. Generated images, videos and extracted game
assets do not belong in program payloads.
Without a public manifest or schema-1 catalogue, basic packages can be inferred
from Scripts/main.lua (case insensitive) or a supported native DLL layout. The
manager preserves actual entrypoint spelling and uses the existing mod folder name
as its ID. An inferred folder name must already satisfy the ID rules above; it is
never silently renamed or truncated. For other names, package the mod under a valid
folder with matching runtime paths, or ask its author for an explicit manifest. It
uses version unversioned, adds an explanatory description, and supplies no
settings or controls. It recognizes config.ini, config.json, settings.json,
config.lua, settings.lua and contents of Config/ as seeds; it excludes
enabled.txt. Add a manifest to remove uncertainty about ownership or settings.
No settings are guessed from executable Lua/C++ source.
Typed settings, help and reset
Each setting needs key, label, type and default. Keys are unique identifiers
matching [A-Za-z_][A-Za-z0-9_]*. Supported types are:
[
{"key":"Mode","label":"Mode","type":"enum","default":"idle","options":["idle","always"]},
{"key":"Speed","label":"Speed","type":"number","default":100,"min":1,"max":1000,"step":1},
{"key":"ToggleKey","label":"Toggle key","type":"key","default":"F12"},
{"key":"Visible","label":"Visible","type":"boolean","default":true},
{"key":"Caption","label":"Caption","type":"string","default":"Hello"}
]
Numbers must be finite and within inclusive bounds; booleans are not numbers.
An optional numeric step must be positive and finite. Enum options are unique,
nonempty string arrays, and the default must be an option. Key names are F1-F12,
A-Z, HOME, END, PAGE_UP, PAGE_DOWN, INSERT, DELETE, SPACE, and ZERO-NINE. String
values are at most 4096 characters, single line, with no control characters.
A setting’s optional description is plain text, at most 4096 characters.
option_descriptions is an enum-only object mapping existing option values to
plain text explanations with the same limit. HTML/markup tags are rejected. The
help button explains the setting, options, default and numeric range; it supports
keyboard focus and activation. Reset changes that field to its declared default
in the form. Save settings to apply the form, then restart the game.
Declarative configuration bindings
configuration is an optional nonempty array of targets. A target has exactly
file, format and bindings; format is json, ini or lua, and must match
the file extension. Paths are relative to the mod root and cannot overlap program
files, entrypoints, activation markers or another configuration target. Each
setting must bind exactly once; unknown setting keys and duplicate or overlapping
destinations are rejected. Do not include the same settings declaration in
multiple examples below; choose the format your mod actually consumes.
{"file":"config.json","format":"json","bindings":{
"Speed":{"path":["camera","speed"]},
"Visible":{"path":["camera","visible"]}
}}
JSON paths are nonempty arrays of nonempty string object keys. Arrays are not addressable; a path crossing an existing scalar or array is rejected. Missing keys use declared defaults and can be created on save. Unknown object keys are preserved. JSON is parsed and serialized as data, with duplicate keys and nonfinite numbers rejected.
{"file":"config.ini","format":"ini","bindings":{
"Speed":{"section":"Camera","key":"Speed"},
"Visible":{"section":"Camera","key":"Visible"}
}}
INI bindings identify a section and key, compared without case. Simple key=value
and key:value records are supported. Existing comments, unrelated lines, newline
style and BOM are preserved. Unsupported or ambiguous syntax, duplicate
sections/keys, interpolation, multiline values and control/line separator injection
are rejected before any write. Values use their declared types rather than
unrestricted string replacement.
{"file":"settings.lua","format":"lua","bindings":{
"Speed":{"key":"Speed"},
"Visible":{"key":"Visible"}
}}
Lua configuration is restricted to one returned table of scalar literals, for
example return { Speed = 100, Visible = true }. String-key syntax such as
["Speed"] = 100 is also supported. No function calls, expressions, nested tables
or executable statements are evaluated. Saving preserves unknown scalar keys but
may normalize formatting. Unsupported Lua syntax leaves the original intact and
reports an actionable error. All configuration targets are checked before changes
are committed together with backups.
For legacy schema-1 mods without configuration, the manager retains its
settings.json/generated settings.lua behavior. The mod must consume its chosen
file at runtime, validate values and retain sensible defaults if it is missing.
Declaring a settings form alone does not make a mod use those values. Runtime Lua
loading belongs to the mod; the manager never evaluates it during inspection.
Sources and updates
Every community source has an independent UUID and cache. Mod identity includes its source; identical IDs from different sources remain separate library entries. They still target UE4SS’s same folder name, so the manager reports a folder ownership conflict instead of overwriting another source’s installed mod.
- A public GitHub repository follows the default branch saved when it was added. Each refresh resolves that branch to an immutable commit and downloads its ZIP. A later change to the repository’s default branch does not silently switch it.
- A release tag follows that tag; a latest-release source follows the latest release. The manager selects a compatible ZIP asset. Multiple assets require an explicit choice; a renamed/disappeared selected asset offers the current ZIPs. Source-only repositories offer release choices when available. The manager never compiles them or runs their installers.
- A direct HTTPS ZIP follows its saved URL. HTTP downloads and redirects away from HTTPS are rejected; downloads and expanded packages have size limits.
- Local ZIPs/folders remain on their saved snapshot until explicitly replaced. Use Update from ZIP and reselect a package. Refresh sources does not reread a local path automatically.
Refresh retains selected mod IDs. A previously known mod absent upstream remains in the library as unavailable so installed content can still be managed; it cannot be installed from that source until it returns. Corrupt downloads, invalid packages, checksum mismatches and failed registry updates retain the previous valid cached source. Adding or refreshing a source does not install its mods.
Official catalogue, images and videos
The official repository uses root catalog.json with schema_version: 1 and a
mods array. Each mod object uses the fields above except schema_version, which
belongs to the catalogue. Payloads live at Mods/<ID>/<relative-path>. Existing
entries that omit entrypoints retain Scripts/main.lua as their entrypoint.
The official source keeps its fixed identity official.
Optional images describe personal PNG targets separately from payloads:
[{"file":"portrait.png","label":"Portrait","width":1110,"height":2156,"background":"transparent","scale":100,"top":0}]
Use transparent or green backgrounds, dimensions at most 8192 per side and
16 million total pixels, scale 1-500 percent, and top offset -100 to 100 percent.
The GUI supplies composition controls and backs up prior images when applying.
Set both video_list and video_folder to enable video targets. video_list must
be a declared program text file such as VIDEOS.txt; each line identifies an
allowed game-relative MP4 path, for example Bacchus/Movie/Fam/T_FAM_BOW_A.mp4.
The current UI supports these Bacchus/Movie/ paths. Use a separate media folder
such as Movies; do not target program/config directories. Personal video files
are not package payloads.
Validation and examples
From the repository root:
python -m manager.validate_mod path/to/mod-folder
python -m manager.validate_mod path/to/package.zip
python -m manager.validate_mod examples/manager-mods/ExampleLua
python -m unittest discover -s tests
The CLI prints identified mod IDs, Lua/native types, file counts and setting
counts. Exit 0 means structurally valid; exit 1 means invalid. It never starts
the game, installs mods, runs build scripts or loads mod code. For the official
working tree, python -m manager.validate_mod . validates its declared catalogue.
See the synthetic templates. The Lua template is complete. The native template contains source and a manifest; its DLL is intentionally absent, so validation fails until a matching build is staged. Test installation, settings, updates, disable and removal with a disposable fake game folder first. Runtime game testing is separate; no template or validation result guarantees behavior in the actual game. Never add diagnostic probes or these synthetic templates to the public playable-mod catalogue.