One plugin container. A shared native core. SDKs for your host language.
Documentation · Examples · Downloads · Roadmap · License
English Wiki · Getting started · Author a plugin · Host integration
The Wiki contains 23 detailed topic pages, a sidebar and a footer; its versioned English sources are maintained with the repository.
A standalone plugin container and native SDK for applications that need to
inspect, validate, build and select components before executing them. A
.ylplugin has its own indexed binary format and embeds the existing YLSpec
metadata frame. It is not a renamed ZIP and does not require YLPkg or LeoMiniGames.
Latest GitHub release: YLPlugin v0.1.3, LGPLv3. Available on GitHub Releases, npm, PyPI and Maven Central. Published native SDKs cover Linux x86_64/ARM64, macOS x86_64/ARM64 and Windows x86_64. No stable ABI or production security audit is claimed during 0.x.
Development branch: 0.1.4. The first presentation-catalog validator and schema contract are implemented in C++; automatic file discovery and selective asset I/O remain planned. Install examples below target 0.1.3. npm 0.1.3 publication is awaiting token permissions; see the publishing record.
0.1.3 highlights. This release adds bounded-memory plaintext validation, cancellation fixes, direct metadata-only reads, bundled CLI installation, strict Node Unicode paths and incremental build versioning. See the changelog, performance guide and troubleshooting. Installation commands below target 0.1.3. See the release notes for the complete scope.
Development verification passed: all seven core CI jobs and all six SDK/platform packaging jobs. See executed checks for results and platform limits.
New in 0.1.3: read the fixed container header and embedded YLSpec
frame directly, without opening a Package, scanning its TOC or reading payloads.
Discovery reads 128 + metadata_frame_length bytes even for multi-gigabyte plugins.
from ylplugin import Library
metadata_toml = Library().read_metadata("package.ylplugin")ylplugin metadata package.ylplugin --jsonThe same native operation is available in C/C++, JavaScript/TypeScript and Java/Kotlin. Metadata contains unverified claims; integrity, signatures and host preflight are separate checks. See exact read scope and API examples.
Installation in 0.1.3: Python platform wheels bundle the core and native CLI;
pip registers ylplugin in the active environment. npm supplies the same CLI via
its bin entry. Java/Kotlin resolve the core transitively and can invoke the
bundled command through xyz.younglion.ylplugin.Cli. See
installation and PATH behavior. These additions are
new in 0.1.3.
The roadmap adds conventional discovery of icons, README, license, contributing and security documents during packaging. Metadata will hold file descriptors only; a separate native discovery API will read just a selected file, without scanning the TOC or unrelated payload. The architecture proposal explains direct byte locators, deterministic writer planning, compatibility and trust. This feature is planned for the next 0.1.x milestone; it is not implemented in 0.1.3.
| SDK | Implementation | Package / build |
|---|---|---|
| C / C++20 | Public C ABI and RAII handle | YLPlugin::ylplugin, build instructions |
| JavaScript / TypeScript | Node-API over the same native core; ESM/CJS and declarations | npm, API |
| Java 11+ | JNI, AutoCloseable, structured maps/lists |
Maven Central, API |
| Kotlin / JVM 11+ | Idiomatic use helpers over the Java/JNI library |
Maven Central, API |
| Python 3.11+ | Typed ctypes facade; native runtime in platform wheels | PyPI, API |
The npm package and JVM native JAR collect only binaries built and tested by the language CI matrix. Python wheels are tagged for their actual platform. Source builds and unsupported platforms can supply an explicit native library path. There is no second JS, Java or Python container parser and no runtime binary download during SDK import. See compatibility.
Python and Node.js packages are published separately from the source release:
python -m pip install ylplugin==0.1.3
npm install @younglionorganization/[email protected]Python wheels include the native ctypes runtime. The npm package includes the tested desktop Node prebuilds; TypeScript declarations ship in the same package. Check the platform requirements before installation. For JVM dependencies and Central availability, see the JVM guide.
Run these examples from a checkout, using the included data container:
import json
from ylplugin import Library
with Library().open("examples/artifacts/data.ylplugin") as plugin:
plugin.validate()
catalog = json.loads(plugin.read("catalog.json"))
print(catalog["total"]) # 42import {Package} from '@younglionorganization/ylplugin';
const plugin = new Package('examples/artifacts/data.ylplugin');
try {
plugin.validate();
console.log(JSON.parse(plugin.read('catalog.json')).total); // 42
} finally {
plugin.close();
}Complete runnable examples: Python, JavaScript, Java, Kotlin and C++.
flowchart LR
Container[".ylplugin container"] --> Core["C++20 container core"]
Core --> Metadata["Embedded YLSpec metadata"]
Core --> Resources["Indexed resources and integrity"]
Core --> C["C ABI: Python ctypes"]
Core --> Node["Node-API: JavaScript / TypeScript"]
Core --> JNI["JNI: Java / Kotlin"]
Core --> CLI["Inspection and build CLI"]
Metadata --> Preflight["Host compatibility and permissions"]
Resources --> Preflight
Preflight --> Approval["Explicit host approval"]
Approval --> Adapters["Data / native / optional Qt RCC"]
The host supplies its own runtime capabilities and permission grants. SDK loading, package validation and plugin activation are separate operations. WASM execution in the example is supplied explicitly by the host.
- Public YLSpec profile
xyz.younglion.plugin/1.0, native validator and schema. - Indexed store/Zstd resources, SHA256 integrity, bounded reads and verified slices.
- Multiple hosts, runtimes and entrypoints with deterministic preflight/fallback.
- Required/optional string, bitmask and byte permissions interpreted by the host.
- Ed25519 signatures, AES-256-GCM encryption and separate trust/license callbacks.
- POSIX transactional extraction, data/native adapters and optional memory RCC mounting.
- C/C++/JS/TS/Java/Kotlin/Python examples, conformance vectors and adversarial tests.
Requirements: CMake 3.26+, C++20/C11 compilers, YLSpec 0.1.2+, OpenSSL 3+, Zstd, nlohmann-json 3.11+. Qt is optional and is not a dependency of the core or language SDKs.
cmake -S . -B build -G Ninja -DYLPLUGIN_YLSPEC_SOURCE=../YLSpec
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure
build/ylplugin inspect examples/artifacts/data.ylplugin --json
build/ylplugin validate examples/artifacts/data.ylplugin
build/ylplugin check examples/artifacts/data.ylplugin --host examples/data/host.jsonFor native Node/JNI builds and platform packaging, follow building.
The existing .rcc conversion command remains available:
build/ylplugin convert legacy-game.rcc --manifest plugin.ylspec --output game.ylplugin| Example | Demonstrates |
|---|---|
| Data catalog | JSON resource, multiple hosts, exact integer permissions; no Qt |
| WebAssembly add | Verified WASM bytes and an explicit Node host runtime |
| Native C plugin | Separate native ABI, external digest approval, prepare/start/stop/cleanup |
| RCC/QML | Byte-preserving RCC conversion and optional memory-backed Qt mounting |
| Encrypted/signed data | Fresh keys, entitlement callback, signatures and tamper rejection |
examples/artifacts includes real RCC, data and WASM containers. Native examples
are generated for the actual build platform; private keys are never checked in.
Metadata inspection and preflight execute no plugin code. validate checks
structure/profile/content; verify authenticates stored bytes separately. Neither
permission declarations nor signatures grant native/publisher authority. Hosts
must approve native code and independently validate/review RCC before Qt parses it.
Native execution is not sandboxed. The WASM example supplies its own host runtime;
there is no built-in WASM or Python execution adapter.
Secure Windows extraction, mobile device validation and an independent release security audit remain open. SDK installation, SDK-native library loading and plugin activation are separate operations. See security.
The release pipeline requires core and language SDK builds from the same commit. It validates provenance, package identities, licenses and every artifact checksum before publishing. The release notes, publishing record and test report record the scope, workflows and platform limits. Historical releases stay immutable.
Start with the documentation guide, examples, CLI reference or the normative format. Publishing explains organization secrets, immutable artifacts, registry scopes and the manual npm/PyPI/Maven workflows. The availability check never prints secret values and does not publish packages.
YLPlugin is licensed under LGPL-3.0-only: LICENSE, incorporated GPLv3 terms and licensing guide. Packages include the license texts and corresponding project source; see SOURCES.md. Third-party dependency terms remain separate.
Maintained by Cavanshirpro under YoungLionOrganization.
For bug reports and development verification, see contributing.
Support development through the repository's configured YoungLionOrganization Patreon.