OracleLoadstar/SCE-Universe_Java_Edition
用户指南Mod加载器

使用Mod

本文档解释了在 SCE-Universe Java Edition 中如何使用、安装和开发模组（Mod），以及模组加载器的工作原理。

概述

SCE-Universe Java Edition 支持通过模组（Mod）扩展其功能。模组是一种外部插件，以 JAR 文件的形式提供，可以为应用程序添加新特性、修改现有行为或提供自定义用户界面。模组系统旨在提供灵活的扩展能力，允许社区开发者为应用程序贡献更多内容。

核心概念包括：

  • 模组主类 (Mod Main Class)：每个模组都需要一个实现 modloader_main 接口的类作为其入口点。
  • 模组元数据 (@target 注解)：通过 target 注解为模组提供名称、作者、版本和描述等信息。
  • 模组加载器 (ModLoader)：负责发现、加载和初始化模组。

架构

SCE-Universe Java Edition 的模组加载系统主要由 modloader_main 接口、@target 注解和 modlist 类组成。用户将编译好的模组 JAR 文件放置在指定目录后，modlist 会扫描这些文件，加载符合条件的模组，并初始化它们。

加载图表中...

架构说明：

  1. 用户操作：开发者或用户首先需要将编译好的模组 JAR 文件放置在应用程序根目录下的 plugins/ 或 plugins/preload/ 文件夹中。
  2. 模组加载入口：应用程序启动时，modlist 类中的 loadmod() 或 _loadmod() 方法会被调用，作为模组加载过程的起点。
  3. 目录扫描与类加载：加载器会扫描指定目录下的所有 JAR 文件，并使用 URLClassLoader 动态加载这些 JAR 文件中的类。
  4. 模组识别：一旦找到一个模组主类，加载器会检查该类是否使用了 cn.oraclestar.sce.system.modloader.target 注解。通过反射，加载器可以获取模组的名称、作者、版本和描述等信息。
  5. 实例化与初始化：加载器会实例化模组主类，并调用其 onEnable() 方法，完成模组的启动和初始化工作。
  6. 模组注册：加载成功后，模组的元数据和其主类实例会被存储在 modlist_List 和 modlist_core 静态 Map 中，供应用程序的其他部分使用。

Mod 的安装与加载

要使用 Mod，您需要将 Mod 的 JAR 文件放置到特定的目录中。

  1. Mod 目录：
    • plugins/: 这是标准 Mod 的放置目录。大多数 Mod 都应该放在这里。
    • plugins/preload/: 这个目录下的 Mod 会在标准 Mod 之前加载（虽然在当前实现中 _loadmod 尚未明确调用，但其设计意图是预加载）。对于需要在其他 Mod 之前初始化的特殊 Mod，可以考虑放置于此。
  2. 安装步骤：
    • 找到您下载的 Mod 的 .jar 文件。
    • 将该 .jar 文件复制到 SCE-Universe Java Edition 应用程序根目录下的 plugins/ 文件夹中。如果 plugins/ 文件夹不存在，请手动创建一个。
    • 重新启动 SCE-Universe Java Edition 应用程序。Mod 加载器将在启动时自动发现并加载您安装的 Mod。

Mod 开发与结构

如果您是 Mod 开发者，希望为 SCE-Universe Java Edition 编写自己的 Mod，您需要遵循以下结构：

1. 实现 modloader_main 接口

您的 Mod 的主类必须实现 cn.oraclestar.sce.system.modloader.modloader_main 接口。这个接口定义了 Mod 生命周期中的关键方法。

java
1package cn.oraclestar.sce.system.modloader; 2 3public interface modloader_main { 4 final String pluginName = ""; // 注意: 实际名称通过 @target 注解提供 5 final String version = ""; // 注意: 实际版本通过 @target 注解提供 6 void onEnable(); // Mod 启用时调用，进行初始化 7 void onDisable(); // Mod 禁用时调用 (目前加载器未明确调用此方法) 8 void innerToPage(cn.oraclestar.sce.system.UI.UI_core ui_core,int now_page); // 允许 Mod 渲染自定义 UI 9 int innerHandle(String Input,int now_page); // 允许 Mod 处理自定义 UI 的输入 10}

Source: src/cn/oraclestar/sce/system/modloader/modloader_main.java

2. 使用 @target 注解

您需要使用 cn.oraclestar.sce.system.modloader.target 注解来为您的 Mod 提供元数据，如名称、作者、版本和描述。这个注解必须应用于您的 Mod 主类。

java
1package cn.oraclestar.sce.system.modloader; 2 3import java.lang.annotation.ElementType; 4import java.lang.annotation.Retention; 5import java.lang.annotation.RetentionPolicy; 6import java.lang.annotation.Target; 7 8@Target(ElementType.TYPE) // 注解应用于类 9@Retention(RetentionPolicy.RUNTIME) // 注解在运行时可用 10public @interface target { 11 String name(); // Mod 的名称 (必填) 12 String author() default "未知"; // 作者名称 (可选，默认"未知") 13 String version() default "1.0.0"; // Mod 版本 (可选，默认"1.0.0") 14 String Description() default "None"; // Mod 描述 (可选，默认"None") 15}

Source: src/cn/oraclestar/sce/system/modloader/target.java

3. 示例 Mod 实现

这是一个简单的 Mod 示例，展示了如何实现 modloader_main 接口并使用 @target 注解。

java
1// 这是一个示例 Mod 的骨架，非实际存在于仓库中，用于演示 Mod 结构。 2package com.yourcompany.mymod; 3 4import cn.oraclestar.sce.system.modloader.modloader_main; 5import cn.oraclestar.sce.system.modloader.target; 6import cn.oraclestar.sce.system.UI.UI_core; // 假设 UI_core 存在于此路径 7 8@target(name = "MyAwesomeMod", author = "ModDeveloper", version = "1.0.0", Description = "这是一个很棒的示例 Mod。") 9public class MyAwesomeMod implements modloader_main { 10 11 @Override 12 public void onEnable() { 13 System.out.println("[MyAwesomeMod] Mod 已启用！"); 14 // 在这里执行 Mod 的初始化逻辑，例如注册事件监听器、加载资源等 15 } 16 17 @Override 18 public void onDisable() { 19 System.out.println("[MyAwesomeMod] Mod 已禁用！"); 20 // 在这里执行 Mod 的清理逻辑 21 } 22 23 @Override 24 public void innerToPage(UI_core ui_core, int now_page) { 25 // 如果 Mod 需要在特定页面渲染自定义 UI，可以在这里实现 26 if (now_page == 5) { // 假设页面 5 是 Mod 自定义页面 27 System.out.println("[MyAwesomeMod] 渲染自定义 Mod UI..."); 28 // ui_core.renderSomething(...); 29 } 30 } 31 32 @Override 33 public int innerHandle(String Input, int now_page) { 34 // 如果 Mod 需要处理特定页面的用户输入，可以在这里实现 35 if (now_page == 5) { 36 System.out.println("[MyAwesomeMod] 收到输入: " + Input); 37 // 根据输入处理逻辑 38 return 0; // 返回一个状态码 39 } 40 return -1; // 不处理此页面 41 } 42}

Source: 此示例代码是根据 modloader_main.java和target.java 接口和注解结构，为说明目的而创建的示例，并非直接从仓库中提取。

API 参考

cn.oraclestar.sce.system.modloader.modloader_main 接口

此接口定义了所有可加载 Mod 必须实现的基本行为。

方法：

  • void onEnable()

    • 描述：当 Mod 被成功加载并启用时调用。Mod 应该在此方法中执行其初始化任务，例如设置事件监听器、加载配置、注册命令等。
    • 参数：无
    • 返回：无

  • void onDisable()

    • 描述：当 Mod 被禁用时调用。Mod 应该在此方法中执行清理任务，例如注销事件监听器、保存数据、释放资源等。
    • 参数：无
    • 返回：无
    • 注意：在当前的 ModLoader 实现中，此方法未被主动调用。

  • void innerToPage(cn.oraclestar.sce.system.UI.UI_core ui_core, int now_page)

    • 描述：允许 Mod 在应用程序的特定页面上渲染自定义用户界面元素。
    • 参数：
      • ui_core (cn.oraclestar.sce.system.UI.UI_core)：提供 UI 渲染能力的上下文对象。
      • now_page (int)：当前正在渲染的页面ID。
    • 返回：无

  • int innerHandle(String Input, int now_page)

    • 描述：允许 Mod 处理应用程序特定页面的用户输入。
    • 参数：
      • Input (String)：用户输入的字符串。
      • now_page (int)：当前接收输入的页面ID。
    • 返回：int 类型状态码，具体含义取决于 Mod 的实现。

cn.oraclestar.sce.system.modloader.target 注解

此注解用于为 Mod 主类提供元数据。

属性：

  • String name()

    • 描述：指定 Mod 的唯一名称。这是识别 Mod 的主要标识符。
    • 默认值：无 (必填)

  • String author()

    • 描述：指定 Mod 的作者名称。
    • 默认值："未知"

  • String version()

    • 描述：指定 Mod 的版本号。
    • 默认值："1.0.0"

  • String Description()

    • 描述：提供 Mod 的简短描述。
    • 默认值："None"

相关链接

Sources

(3 files)
modlist.javamodloader_main.javatarget.java

安装与运行

Previous Page

Mod文件夹结构

Next Page

On this page

使用Mod概述架构Mod 的安装与加载Mod 开发与结构1. 实现 modloadermain 接口2. 使用 @target 注解3. 示例 Mod 实现API 参考cn.oraclestar.sce.system.modloader.modloadermain 接口cn.oraclestar.sce.system.modloader.target 注解相关链接