Skip to content
YoungLionOrganizationPublic

About

Portable .ylplugin containers and native C++20/C, JavaScript/TypeScript, Java/Kotlin and Python SDKs. Integrity, signing, encryption, host preflight and optional Qt RCC. LGPLv3.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

YLPlugin

Release Core CI Language SDKs PyPI version PyPI distributions npm version Maven Central Format: 1.0 C11 ABI C++20 JavaScript / TypeScript Java / Kotlin Python Platforms License: LGPLv3 Support on Patreon

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.

Discover plugins by reading only their YLSpec metadata

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 --json

The 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.

Planned: plugin front-page assets

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.

Choose an SDK

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.

Installation and quick starts

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"])  # 42
import {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++.

Architecture

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"]
Loading

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.

What works

  • 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.

Build and inspect

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.json

For 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

More than RCC

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.

Trust boundaries

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.

Release verification

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.

Documentation

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.

About

Portable .ylplugin containers and native C++20/C, JavaScript/TypeScript, Java/Kotlin and Python SDKs. Integrity, signing, encryption, host preflight and optional Qt RCC. LGPLv3.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages