非官方Homestuck合集项目Mod开发指南

概述

本文将详细介绍如何为非官方Homestuck合集项目开发功能扩展模块(Mod)。该项目提供了一个完善的Mod开发API，允许开发者通过编写JavaScript代码来修改合集内容、添加新功能或自定义界面。

Mod开发基础

开发环境准备

开发Mod需要具备基本的JavaScript编程知识。Mod本质上是一个JavaScript模块，可以通过修改合集数据或添加新内容来实现各种功能。

Mod类型

项目支持两种形式的Mod：

1. 单文件脚本(.js文件)
2. 包含多个文件的Mod文件夹

单文件脚本适合简单的修改，而Mod文件夹则适合需要包含资源文件(如图片、CSS等)的复杂Mod。

Mod开发详解

元数据定义

每个Mod必须包含以下元数据字段：

module.exports = {
    title: "Mod标题",
    summary: "简短描述",
    description: "详细描述(支持HTML)",
    author: "作者名",
    modVersion: 1.0,
    locked: "001901" // 可选，指定解锁页面
}

核心功能实现

修改合集内容

通过edit函数可以修改合集的核心数据：

edit(archive) {
    // 修改特定页面内容
    archive.mspa.story['001901'].content = "新内容";
    
    // 添加首页图标
    archive.tweaks.modHomeRowItems.unshift({
        href: "/custom-page",
        thumbsrc: "assets://path/to/image.png",
        title: '自定义页面',
        description: '<p>自定义描述</p>'
    });
}

资源重定向

使用routes系统可以重定向资源文件：

routes: {
    'assets://原文件路径': './mod文件夹中的新文件'
}

批量资源替换

对于需要替换大量文件的情况，可以使用trees：

trees: {
    './mod文件夹/资源目录/': 'assets://目标目录/'
}

界面定制

添加自定义样式

styles: [
    {source: "./custom.css"} // 注入CSS文件
]

创建主题

themes: [
    {
        label: "主题名称",
        source: "./theme.scss" // SCSS格式主题文件
    }
]

高级功能

添加注释

可以为特定页面添加脚注：

footnotes: [{
    author: "注释作者",
    story: {
        "001901": [{
            content: "注释内容<em>支持HTML</em>"
        }]
    }
}]

运行时计算

使用computed函数可以在Mod加载时执行动态计算：

computed(api) {
    return {
        edit(archive) {
            // 使用api访问各种功能
            const data = api.readJson("./data.json");
            // 修改archive
        }
    }
}

用户设置

可以为Mod添加配置选项：

settings: {
    boolean: [{
        model: "enableFeature",
        label: "启用功能",
        desc: "启用实验性功能"
    }],
    radio: [{
        model: "themeStyle",
        label: "主题风格",
        options: [
            {value: "light", label: "明亮"},
            {value: "dark", label: "暗黑"}
        ]
    }]
}

最佳实践

1. 避免直接覆盖内容：尽量使用修改而非完全替换现有内容
2. 合理使用资源重定向：优先使用routes和trees系统而非直接修改media路径
3. 考虑兼容性：注意Mod之间的加载顺序和可能的冲突
4. 性能优化：对于大量资源替换，使用trees比多个routes更高效

调试与测试

1. 使用api.logger输出调试信息
2. 修改后可能需要重新加载页面才能看到效果
3. 某些重大修改可能需要重启应用

总结

非官方Homestuck合集项目的Mod系统提供了强大的扩展能力，从简单的内容修改到复杂的界面定制都可以实现。开发者可以根据需要选择合适的API接口，按照规范开发出功能丰富的Mod。

通过本文介绍的核心概念和API使用方法，开发者应该能够开始创建自己的Mod。建议从简单的修改开始，逐步尝试更复杂的功能开发。