新手教程

📚 新手教程

从零开始构建二次元恋爱世界观

使用 MediaWiki + Semantic MediaWiki + Lua 打造你的幻想世界

📖 教程概览

欢迎来到星之丘物语的世界观构建教程！本教程将带你从零开始，学习如何使用 MediaWiki 技术栈构建一个完整的二次元恋爱故事世界。

🎯 你将学到什么？

📝 如何使用 Lua 编写游戏系统（好感度系统）
🎨 如何设计美观的角色和事件模板
🔗 如何使用 Semantic MediaWiki 管理角色关系
🧪 如何编写和运行单元测试
🌐 如何构建一个完整的世界观体系

第一章：技术栈介绍

🛠️ 核心技术

我们的世界观构建基于以下技术：

技术	用途	示例
MediaWiki	基础 Wiki 平台	页面管理、分类、模板系统
Scribunto (Lua)	编写游戏逻辑	好感度计算、等级判断、进度条生成
Semantic MediaWiki	结构化数据存储	角色属性、事件关系、数据查询
HTML/CSS	美化页面外观	渐变背景、卡片布局、响应式设计

📁 项目结构

星之丘物语/
├── Module:Affection          # 好感度系统核心逻辑
├── Module:AffectionTest      # 单元测试模块
├── Template:角色              # 角色信息展示模板
├── Template:事件              # 事件展示模板
├── Template:Quote            # 语录引用模板
├── Template:好感度展示        # 好感度演示模板
├── 樱井明日香                # 角色页面示例
├── 月见雫                    # 角色页面示例
├── 图书馆的邂逅              # 事件页面示例
└── 单元测试                  # 测试中心页面

第二章：Lua 模块 - 好感度系统

💡 什么是 Lua 模块？

Lua 模块是 MediaWiki 中用于编写复杂逻辑的工具。通过 Scribunto 扩展，我们可以在 Wiki 中运行 Lua 代码。

🌟 为什么选择 Lua？

⚡ 性能优秀，适合复杂计算
🔧 语法简洁，易于学习
🎮 广泛应用于游戏开发
🔄 可以缓存结果，减少服务器负担

📊 好感度系统设计

我们的好感度系统包含 6 个等级，每个等级有不同的图标和颜色：

💔 陌生10 / 100

💙 认识30 / 100

💚 友好50 / 100

🧡 亲密70 / 100

💖 喜欢90 / 100

❤️ 热恋100 / 100

💻 代码解析

让我们看看好感度系统的核心代码：

-- 等级配置表
local LEVELS = {
    {min = 0,   max = 19,  name = "陌生", icon = "💔", color = "#999999"},
    {min = 20,  max = 39,  name = "认识", icon = "💙", color = "#88ccff"},
    {min = 40,  max = 59,  name = "友好", icon = "💚", color = "#66dd88"},
    {min = 60,  max = 79,  name = "亲密", icon = "🧡", color = "#ffaa44"},
    {min = 80,  max = 99,  name = "喜欢", icon = "💖", color = "#ff6699"},
    {min = 100, max = 100, name = "热恋", icon = "❤️", color = "#ff0066"}
}

-- 获取等级信息
function p.getLevel(affection)
    for _, level in ipairs(LEVELS) do
        if affection >= level.min and affection <= level.max then
            return level
        end
    end
    return LEVELS[1]  -- 默认返回第一级
end

📝 设计要点：

使用表格存储配置，易于扩展和修改
每个等级有独立的颜色和图标
通过循环查找，代码简洁高效

🎨 进度条生成

进度条是如何生成的？看这段代码：

function p.show(frame)
    local affection = tonumber(frame.args[1]) or 0
    local level = p.getLevel(affection)
    
    -- 计算进度百分比
    local range = level.max - level.min + 1
    local progress = (affection - level.min) / range * 100
    
    -- 生成 HTML
    local html = mw.html.create('div')
    html:css('background', 'linear-gradient(90deg, ' .. level.color .. ' ' .. progress .. '%, #e0e0e0 ' .. progress .. '%)')
        :css('border-radius', '10px')
        :css('padding', '10px')
        :wikitext(level.icon .. ' ' .. level.name .. ' (' .. affection .. '/100)')
    
    return tostring(html)
end

效果演示：

🧡 亲密65 / 100

第三章：Semantic MediaWiki - 数据管理

🔍 什么是 Semantic MediaWiki？

Semantic MediaWiki（SMW）是一个强大的扩展，可以将 Wiki 变成一个结构化数据库。

❌ 传统 Wiki

只能存储文本
查询困难
无法建立关系
数据分散

✅ 使用 SMW

结构化数据存储
强大的查询功能
自动建立关系
数据可视化

📝 属性定义示例

在角色模板中，我们使用 `` 定义属性：

{{#set:
|名字=樱井明日香
|年龄=17
|性别=女
|身高=165cm
|生日=3月15日
|血型=A型
|性格=温柔、善良、有点天然呆
|好感度=65
|声优=早见沙织
}}

💡 为什么使用 #set 而不是值？

`{{#set:}}` 方式不会在页面上显示属性值，保持页面整洁
`值` 会在页面上回显，造成重复显示
两种方式都会存储到 SMW 数据库

🔎 数据查询示例

查询所有女性角色，按好感度排序：

{{#ask:
 [[Category:角色]]
 [[性别::女]]
 |?名字
 |?年龄
 |?好感度
 |sort=好感度
 |order=desc
 |format=table
}}

查询结果：

	名字	年龄	好感度
樱井明日香	樱井明日香	17	65
月见雫	月见雫	17	45

📊 查询说明：

这个查询会自动列出所有女性角色
数据来自各个角色页面的 `` 属性
按好感度从高到低排序
使用表格格式展示，易于阅读
如果没有数据，说明还没有创建符合条件的角色页面

第四章：模板系统 - 美化页面

🎨 角色模板设计

角色模板 `Template:角色` 是页面美化的核心。让我们看看它的结构：

模板调用示例：

{{角色
|名字=樱井明日香
|英文名=Sakurai Asuka
|年龄=17
|性别=女
|身高=165cm
|好感度=65
|性格=温柔、善良、有点天然呆
|爱好=烘焙、阅读、照顾小动物
|声优=早见沙织
}}

渲染效果：

实际页面上会显示一个精美的角色信息卡片，包含：

📸 角色立绘（如果提供）
💕 实时好感度进度条
📋 基本信息表格
🌸 性格描述
💝 兴趣爱好

🎭 事件模板设计

事件模板 `Template:事件` 用于展示游戏事件：

{{事件
|标题=图书馆的邂逅
|角色=樱井明日香
|地点=星之丘学园图书馆
|时间=放学后
|好感度变化=+15
|类型=日常
|描述=放学后，你来到图书馆...
|选项1=轻声打招呼："在读《雪国》吗？"
|结果1=明日香抬起头，脸上露出温柔的笑容...
}}

特点：

🎨 蓝色渐变背景（与角色的粉色区分）
🎯 支持最多 4 个选项
📊 显示好感度变化
🏷️ 自动分类和关联

💬 语录模板

`Template:Quote` 用于美化角色台词：

{{quote|没关系的，我会一直陪在你身边。|樱井明日香}}

效果：

"

没关系的，我会一直陪在你身边。

— 樱井明日香

第五章：CSS 样式技巧

🌈 渐变背景

我们大量使用 CSS 渐变创造视觉层次：

/* 角色卡片 - 粉色渐变 */
background: linear-gradient(135deg, #fff5f8 0%, #ffe8f0 100%);

/* 事件卡片 - 蓝色渐变 */
background: linear-gradient(135deg, #e3f2fd 0%, #bbdefb 100%);

/* 教程页面 - 紫色渐变 */
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

角色主题
粉色系

事件主题
蓝色系

系统主题
紫色系

🎯 响应式设计

使用 Grid 布局实现响应式卡片：

display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 20px;

这样的布局会自动适应屏幕宽度：

📱 手机：1 列
💻 平板：2 列
🖥️ 电脑：3-4 列

第六章：单元测试

🧪 为什么需要测试？

⚠️ 没有测试的代码是不可靠的！

想象一下，如果好感度计算错误：

😱 玩家辛苦提升好感度，结果数值不变
😰 好感度超过 100 或低于 0
😵 等级显示错误，"热恋"变成"陌生"

单元测试可以自动检测这些问题！

✅ 测试用例示例

在 `Module:AffectionTest` 中，我们编写了 11 个测试：

function p.runTests()
    local results = {}
    
    -- 测试 1：陌生等级
    table.insert(results, {
        name = "陌生等级测试 (10分)",
        expected = "陌生",
        actual = affection.getLevelName(10),
        passed = affection.getLevelName(10) == "陌生"
    })
    
    -- 测试 9：计算测试
    table.insert(results, {
        name = "计算测试 (50+15)",
        expected = 65,
        actual = affection.calculate(50, 15),
        passed = affection.calculate(50, 15) == 65
    })
    
    return results
end

查看测试结果： 单元测试

第七章：完整工作流

🚀 从零开始构建世界观

第 1 步：规划世界观

📖 确定主题（恋爱、冒险、奇幻等）
👥 设计主要角色（3-5 个）
🗺️ 构建世界设定（学校、城市等）
📅 规划事件线（10+ 个事件）

第 2 步：搭建技术基础

🛠️ 安装 MediaWiki + Scribunto + Semantic MediaWiki
📝 创建核心模块（游戏系统逻辑）
🧪 编写单元测试（确保代码质量）

第 3 步：设计模板

🎨 角色模板（展示角色信息）
📋 事件模板（展示游戏事件）
💬 辅助模板（语录、提示框等）

第 4 步：填充内容

👤 创建角色页面（使用角色模板）
📖 创建事件页面（使用事件模板）
🏠 创建主页（汇总展示）

第 5 步：测试和优化

✅ 运行单元测试
🔍 检查页面效果
🎨 优化视觉设计
📱 测试移动端显示

📋 文件清单

类型	文件名	作用	优先级
Lua 模块	Module:Affection	好感度系统核心	⭐⭐⭐⭐⭐
Lua 模块	Module:AffectionTest	单元测试	⭐⭐⭐⭐
模板	Template:角色	角色信息展示	⭐⭐⭐⭐⭐
模板	Template:事件	事件信息展示	⭐⭐⭐⭐⭐
模板	Template:Quote	语录引用	⭐⭐⭐
模板	Template:好感度展示	系统演示	⭐⭐
页面	星之丘物语	主页	⭐⭐⭐⭐⭐
页面	角色页面 × N	角色详情	⭐⭐⭐⭐
页面	事件页面 × N	事件详情	⭐⭐⭐⭐
页面	单元测试	测试中心	⭐⭐⭐
页面	新手教程	本页面	⭐⭐

第八章：进阶技巧

🎓 性能优化

1. 使用缓存

Lua 模块的结果会被自动缓存，减少重复计算：

-- MediaWiki 会缓存这个结果
function p.show(frame)
    local affection = tonumber(frame.args[1]) or 0
    -- ... 复杂计算
    return result
end

2. 懒加载

只在需要时才加载大型模板：

{{#if:{{{显示详情|}}}|
    {{角色详细信息|{{{名字}}}}}
|}}

3. 减少 #ask 查询

SMW 查询比较慢，尽量减少使用：

❌ 在每个角色页面都查询全部角色
✅ 在主页查询一次，分类页面使用分类系统

🔐 数据验证

在模板中验证输入数据：

{{#ifexpr:{{{好感度|0}}} >= 0 and {{{好感度|0}}} <= 100
| {{#invoke:Affection|show|{{{好感度}}}}}
| <span style="color: red;">错误：好感度必须在 0-100 之间</span>
}}

🌍 国际化支持

如果需要多语言支持：

local i18n = {
    zh = {stranger = "陌生", friend = "友好"},
    en = {stranger = "Stranger", friend = "Friend"},
    ja = {stranger = "見知らぬ", friend = "友好"}
}

function p.getLevelName(affection, lang)
    lang = lang or "zh"
    -- 使用对应语言的文本
end

第九章：常见问题

❓ FAQ

Q: Lua 模块报错怎么办？

A: 检查以下几点：

语法错误（缺少 end、括号不匹配）
变量名拼写错误
使用 `mw.log()` 输出调试信息
在单元测试页面查看详细错误

Q: 模板显示不正常？

A: 可能的原因：

参数名拼写错误（区分大小写）
HTML/CSS 语法错误
使用浏览器开发者工具检查

Q: SMW 属性没有存储？

A: 确保：

使用了 `` 或 `值`
属性名没有特殊字符
页面已保存（预览模式不会存储）
运行了 SMW 刷新任务

Q: 好感度进度条不显示？

A: 检查：

Module:Affection 是否已创建
好感度参数是否为数字
是否有 Lua 错误（查看页面底部）

第十章：扩展建议

🚀 如何扩展这个系统？

💝 角色系统

添加更多角色属性（星座、MBTI）
实现角色关系图谱
角色好感度历史记录
角色语音资料库

📖 事件系统

事件分支系统（选择影响后续）
事件触发条件（时间、地点、好感度）
CG 图片展示
事件回放系统

🎮 游戏系统

物品系统（礼物、道具）
成就系统
存档系统
小游戏集成

🌍 世界观

地图系统
时间线系统
设定集
官方小说/漫画

总结

🎉 恭喜你完成教程！

现在你已经掌握了使用 MediaWiki 构建二次元世界观的全部技能！
是时候创建属于你自己的幻想世界了！

📚 相关资源

🤝 参与贡献

如果你有任何改进建议或发现问题，欢迎：

💬 在讨论页留言
🐛 报告 Bug
✨ 提交新功能建议
📝 完善文档

✨ 开始你的创作之旅吧！✨

MediaWiki + 你的想象力 = 无限可能