Add runtime Molang support for ModelEngine

Evaluate preserved YSM expressions per animation frame, expose MythicMobs variable mechanics, and verify the distributable with GitHub Actions.

Author: Arbousier1

.github/workflows/build.yml

@@ -0,0 +1,42 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          gradle-version: '8.14.3'
+
+      - name: Build and test
+        run: gradle --no-daemon clean build
+
+      - name: Upload plugin artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: YsmModelEngineMolang
+          path: build/libs/YsmModelEngineMolang-*.jar
+          if-no-files-found: error
+          retention-days: 14

.gitignore

@@ -0,0 +1,6 @@
+.gradle/
+build/
+out/
+.idea/
+*.iml
+/lib/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenYSM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

THIRD_PARTY_NOTICES

@@ -0,0 +1,9 @@
+Third-party components
+
+Molang compiler
+- Artifact: gg.moonflower:molang-compiler:3.1.1.19
+- License: MIT
+- Project: Ocelot5836/molang-compiler
+
+ModelEngine and Paper APIs are compile-time/runtime dependencies supplied by
+those projects and are not bundled into the plugin JAR.

build.gradle.kts

@@ -0,0 +1,58 @@
+plugins {
+    java
+    id("com.gradleup.shadow") version "8.3.6"
+}
+
+group = property("group") as String
+version = property("version") as String
+
+java {
+    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
+    withSourcesJar()
+}
+
+dependencies {
+    compileOnly("io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT")
+    compileOnly("com.ticxo.modelengine:ModelEngine:R4.1.0") {
+        isTransitive = false
+    }
+    compileOnly("io.lumine:Mythic-Dist:5.13.0-SNAPSHOT") {
+        isTransitive = false
+    }
+
+    implementation("gg.moonflower:molang-compiler:3.1.1.19")
+
+    testImplementation("org.junit.jupiter:junit-jupiter:5.12.2")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+    testCompileOnly("io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT")
+    testCompileOnly("com.ticxo.modelengine:ModelEngine:R4.1.0") {
+        isTransitive = false
+    }
+    testCompileOnly("io.lumine:Mythic-Dist:5.13.0-SNAPSHOT") {
+        isTransitive = false
+    }
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    options.encoding = "UTF-8"
+    options.release.set(21)
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.processResources {
+    filesMatching("plugin.yml") {
+        expand("version" to project.version)
+    }
+}
+
+tasks.shadowJar {
+    archiveClassifier.set("")
+    archiveFileName.set("YsmModelEngineMolang-${project.version}.jar")
+}
+
+tasks.build {
+    dependsOn(tasks.shadowJar)
+}

gradle.properties

@@ -0,0 +1,3 @@
+group=com.ysm
+version=0.1.0-SNAPSHOT
+org.gradle.jvmargs=-Xmx1G -Dfile.encoding=UTF-8

settings.gradle.kts

@@ -0,0 +1,23 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
+    repositories {
+        mavenCentral()
+        maven("https://repo.papermc.io/repository/maven-public/")
+        maven("https://mvn.lumine.io/repository/maven-public/") {
+            metadataSources {
+                mavenPom()
+                artifact()
+            }
+        }
+        maven("https://maven.blamejared.com/")
+    }
+}
+
+rootProject.name = "ysm-modelengine-molang"

src/main/java/com/ysm/modelengine/molang/ClearMolangVariableMechanic.java

@@ -0,0 +1,34 @@
+package com.ysm.modelengine.molang;
+
+import io.lumine.mythic.api.adapters.AbstractEntity;
+import io.lumine.mythic.api.config.MythicLineConfig;
+import io.lumine.mythic.api.skills.INoTargetSkill;
+import io.lumine.mythic.api.skills.ITargetedEntitySkill;
+import io.lumine.mythic.api.skills.SkillMetadata;
+import io.lumine.mythic.api.skills.SkillResult;
+
+final class ClearMolangVariableMechanic implements INoTargetSkill, ITargetedEntitySkill {
+    private final String key;
+    private final EntityVariableStore variables;
+
+    ClearMolangVariableMechanic(MythicLineConfig config, EntityVariableStore variables) {
+        this.key = config.getString(new String[]{"key", "name", "variable"}, "");
+        this.variables = variables;
+    }
+
+    @Override
+    public SkillResult cast(SkillMetadata metadata) {
+        return clear(metadata.getCaster().getEntity());
+    }
+
+    @Override
+    public SkillResult castAtEntity(SkillMetadata metadata, AbstractEntity target) {
+        return clear(target);
+    }
+
+    private SkillResult clear(AbstractEntity target) {
+        if (target == null || target.getUniqueId() == null) return SkillResult.INVALID_TARGET;
+        variables.clear(target.getUniqueId(), key);
+        return SkillResult.SUCCESS;
+    }
+}

src/main/java/com/ysm/modelengine/molang/EntityVariableStore.java

@@ -0,0 +1,62 @@
+package com.ysm.modelengine.molang;
+
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+public final class EntityVariableStore {
+    private final Map<UUID, Map<String, Float>> values = new ConcurrentHashMap<>();
+    private final float defaultValue;
+
+    public EntityVariableStore(float defaultValue) {
+        this.defaultValue = defaultValue;
+    }
+
+    public float get(UUID entityId, String name) {
+        if (entityId == null || name == null || name.isBlank()) return defaultValue;
+        Map<String, Float> entityValues = values.get(entityId);
+        if (entityValues == null) return defaultValue;
+        return entityValues.getOrDefault(normalize(name), defaultValue);
+    }
+
+    public void set(UUID entityId, String name, float value) {
+        if (entityId == null || name == null || name.isBlank()) return;
+        values.computeIfAbsent(entityId, ignored -> new ConcurrentHashMap<>())
+                .put(normalize(name), value);
+    }
+
+    public void clear(UUID entityId, String name) {
+        if (entityId == null) return;
+        if (name == null || name.isBlank()) {
+            values.remove(entityId);
+            return;
+        }
+        Map<String, Float> entityValues = values.get(entityId);
+        if (entityValues == null) return;
+        entityValues.remove(normalize(name));
+        if (entityValues.isEmpty()) values.remove(entityId, entityValues);
+    }
+
+    public Map<String, Float> snapshot(UUID entityId) {
+        if (entityId == null) return Map.of();
+        Map<String, Float> entityValues = values.get(entityId);
+        return entityValues == null ? Map.of() : Map.copyOf(entityValues);
+    }
+
+    public void clearAll() {
+        values.clear();
+    }
+
+    private static String normalize(String name) {
+        return normalizeName(name);
+    }
+
+    static String normalizeName(String name) {
+        if (name == null) return "";
+        String normalized = name.trim().toLowerCase(java.util.Locale.ROOT);
+        if (normalized.startsWith("v.")) return normalized.substring(2);
+        if (normalized.startsWith("variable.")) return normalized.substring("variable.".length());
+        if (normalized.startsWith("ctrl.")) return "ctrl_" + normalized.substring("ctrl.".length());
+        return normalized;
+    }
+}

src/main/java/com/ysm/modelengine/molang/MolangCompilerFacade.java

@@ -0,0 +1,70 @@
+package com.ysm.modelengine.molang;
+
+import gg.moonflower.molangcompiler.api.GlobalMolangCompiler;
+import gg.moonflower.molangcompiler.api.MolangCompiler;
+import gg.moonflower.molangcompiler.api.MolangExpression;
+import gg.moonflower.molangcompiler.api.exception.MolangException;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+final class MolangCompilerFacade {
+    private final MolangCompiler compiler = GlobalMolangCompiler.get();
+    private final Map<String, MolangExpression> cache = new ConcurrentHashMap<>();
+    private final int maxEntries;
+    private final RateLimitedDiagnostics diagnostics;
+
+    MolangCompilerFacade(int maxEntries, RateLimitedDiagnostics diagnostics) {
+        this.maxEntries = Math.max(64, maxEntries);
+        this.diagnostics = diagnostics;
+    }
+
+    MolangExpression compile(String source) {
+        String normalized = normalize(source);
+        if (normalized.isBlank()) {
+            throw new IllegalArgumentException("Molang expression cannot be blank");
+        }
+
+        MolangExpression cached = cache.get(normalized);
+        if (cached != null) return cached;
+
+        MolangExpression expression = compileUncached(normalized);
+        if (cache.size() >= maxEntries) {
+            diagnostics.warn("cache-full", "Molang expression cache is full; using uncached expression: " + normalized);
+            return expression;
+        }
+
+        MolangExpression existing = cache.putIfAbsent(normalized, expression);
+        return existing == null ? expression : existing;
+    }
+
+    void clear() {
+        cache.clear();
+    }
+
+    int size() {
+        return cache.size();
+    }
+
+    private MolangExpression compileUncached(String source) {
+        try {
+            return compiler.compile(source);
+        } catch (MolangException | RuntimeException exception) {
+            diagnostics.warn("compile:" + source,
+                    "Unable to compile Molang expression '" + source + "': " + exception.getMessage());
+            throw new IllegalArgumentException("Invalid Molang expression: " + source, exception);
+        }
+    }
+
+    static String normalize(String source) {
+        if (source == null) return "";
+        String normalized = source.trim();
+        if (normalized.startsWith("molang:")) normalized = normalized.substring("molang:".length()).trim();
+        normalized = normalized.replace("ysm.head_yaw", "query.head_y_rotation");
+        normalized = normalized.replace("ysm.head_pitch", "query.head_x_rotation");
+        normalized = normalized.replace("ysm.body_yaw", "query.body_y_rotation");
+        normalized = normalized.replace("variable.", "v.");
+        normalized = normalized.replace("ctrl.", "v.ctrl_");
+        return normalized;
+    }
+}