Editing 新手教程

{{DISPLAYTITLE:新手教程 - 如何构建二次元世界观}}

<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 40px; border-radius: 15px; text-align: center; margin-bottom: 30px; box-shadow: 0 8px 16px rgba(102, 126, 234, 0.3);">
<div style="font-size: 3em; font-weight: bold; margin-bottom: 15px;">📚 新手教程</div>
<div style="font-size: 1.5em; opacity: 0.95; margin-bottom: 10px;">从零开始构建二次元恋爱世界观</div>
<div style="font-size: 1em; opacity: 0.85;">
使用 MediaWiki + Semantic MediaWiki + Lua 打造你的幻想世界
</div>
</div>

== 📖 教程概览 ==

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

<div style="background: #f0f8ff; border-left: 5px solid #667eea; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''🎯 你将学到什么？'''

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

----

== 第一章：技术栈介绍 ==

=== 🛠️ 核心技术 ===

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

{| class="wikitable" style="width: 100%; margin: 20px 0;"
! style="background: #667eea; color: white; width: 25%;" | 技术
! style="background: #667eea; color: white; width: 35%;" | 用途
! style="background: #667eea; color: white; width: 40%;" | 示例
|-
| '''MediaWiki'''
| 基础 Wiki 平台
| 页面管理、分类、模板系统
|-
| '''Scribunto (Lua)'''
| 编写游戏逻辑
| 好感度计算、等级判断、进度条生成
|-
| '''Semantic MediaWiki'''
| 结构化数据存储
| 角色属性、事件关系、数据查询
|-
| '''HTML/CSS'''
| 美化页面外观
| 渐变背景、卡片布局、响应式设计
|}

=== 📁 项目结构 ===

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

----

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

=== 💡 什么是 Lua 模块？ ===

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

<div style="background: #fff5f8; border-left: 5px solid #ff6699; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''🌟 为什么选择 Lua？'''

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

=== 📊 好感度系统设计 ===

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

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 15px; margin: 20px 0;">
{{#invoke:Affection|show|10}}
{{#invoke:Affection|show|30}}
{{#invoke:Affection|show|50}}
{{#invoke:Affection|show|70}}
{{#invoke:Affection|show|90}}
{{#invoke:Affection|show|100}}
</div>

=== 💻 代码解析 ===

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

<syntaxhighlight lang="lua">
-- 等级配置表
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
</syntaxhighlight>

<div style="background: #f0fff0; border-left: 5px solid #66dd88; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''📝 设计要点：'''

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

=== 🎨 进度条生成 ===

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

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

'''效果演示：'''

{{#invoke:Affection|show|65}}

----

== 第三章：Semantic MediaWiki - 数据管理 ==

=== 🔍 什么是 Semantic MediaWiki？ ===

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

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 20px 0;">
<div style="background: #fff5f8; padding: 20px; border-radius: 10px; border: 2px solid #ff6699;">
<div style="font-size: 20px; font-weight: bold; color: #ff6699; margin-bottom: 10px;">❌ 传统 Wiki</div>
* 只能存储文本
* 查询困难
* 无法建立关系
* 数据分散
</div>

<div style="background: #f0fff0; padding: 20px; border-radius: 10px; border: 2px solid #66dd88;">
<div style="font-size: 20px; font-weight: bold; color: #66dd88; margin-bottom: 10px;">✅ 使用 SMW</div>
* 结构化数据存储
* 强大的查询功能
* 自动建立关系
* 数据可视化
</div>
</div>

=== 📝 属性定义示例 ===

在角色模板中，我们使用 `{{#set:}}` 定义属性：

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

<div style="background: #fffacd; border-left: 5px solid #ffd700; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''💡 为什么使用 #set 而不是 [[属性::值]]？'''

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

=== 🔎 数据查询示例 ===

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

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

'''查询结果：'''

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

<div style="background: #f0f8ff; border-left: 5px solid #667eea; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''📊 查询说明：'''

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

----

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

=== 🎨 角色模板设计 ===

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

<div style="background: #f8f9fa; padding: 20px; border-radius: 10px; border: 1px solid #ddd; margin: 20px 0;">
'''模板调用示例：'''

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

'''渲染效果：'''

实际页面上会显示一个精美的角色信息卡片，包含：
* 📸 角色立绘（如果提供）
* 💕 实时好感度进度条
* 📋 基本信息表格
* 🌸 性格描述
* 💝 兴趣爱好

=== 🎭 事件模板设计 ===

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

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

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

=== 💬 语录模板 ===

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

<syntaxhighlight lang="wikitext">
{{quote|没关系的，我会一直陪在你身边。|樱井明日香}}
</syntaxhighlight>

'''效果：'''

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

----

== 第五章：CSS 样式技巧 ==

=== 🌈 渐变背景 ===

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

<syntaxhighlight lang="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%);
</syntaxhighlight>

<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 15px; margin: 20px 0;">
<div style="background: linear-gradient(135deg, #fff5f8 0%, #ffe8f0 100%); padding: 30px; border-radius: 10px; text-align: center; font-weight: bold; color: #ff6699;">
角色主题<br/>粉色系
</div>
<div style="background: linear-gradient(135deg, #e3f2fd 0%, #bbdefb 100%); padding: 30px; border-radius: 10px; text-align: center; font-weight: bold; color: #1976d2;">
事件主题<br/>蓝色系
</div>
<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 30px; border-radius: 10px; text-align: center; font-weight: bold; color: white;">
系统主题<br/>紫色系
</div>
</div>

=== 🎯 响应式设计 ===

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

<syntaxhighlight lang="css">
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 20px;
</syntaxhighlight>

这样的布局会自动适应屏幕宽度：
* 📱 手机：1 列
* 💻 平板：2 列
* 🖥️ 电脑：3-4 列

----

== 第六章：单元测试 ==

=== 🧪 为什么需要测试？ ===

<div style="background: #fff3cd; border-left: 5px solid #ffc107; padding: 20px; margin: 20px 0; border-radius: 8px;">
'''⚠️ 没有测试的代码是不可靠的！'''

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

单元测试可以'''自动检测'''这些问题！
</div>

=== ✅ 测试用例示例 ===

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

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

'''查看测试结果：''' [[单元测试]]

----

== 第七章：完整工作流 ==

=== 🚀 从零开始构建世界观 ===

<div style="background: linear-gradient(135deg, #e0f7fa 0%, #b2ebf2 100%); padding: 30px; border-radius: 15px; margin: 30px 0;">

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

'''第 2 步：搭建技术基础'''
* 🛠️ 安装 MediaWiki + Scribunto + Semantic MediaWiki
* 📝 创建核心模块（游戏系统逻辑）
* 🧪 编写单元测试（确保代码质量）

'''第 3 步：设计模板'''
* 🎨 角色模板（展示角色信息）
* 📋 事件模板（展示游戏事件）
* 💬 辅助模板（语录、提示框等）

'''第 4 步：填充内容'''
* 👤 创建角色页面（使用角色模板）
* 📖 创建事件页面（使用事件模板）
* 🏠 创建主页（汇总展示）

'''第 5 步：测试和优化'''
* ✅ 运行单元测试
* 🔍 检查页面效果
* 🎨 优化视觉设计
* 📱 测试移动端显示

</div>

=== 📋 文件清单 ===

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

----

== 第八章：进阶技巧 ==

=== 🎓 性能优化 ===

<div style="background: #f5f5f5; padding: 20px; border-radius: 10px; margin: 20px 0;">
'''1. 使用缓存'''

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

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

'''2. 懒加载'''

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

<syntaxhighlight lang="wikitext">
{{#if:{{{显示详情|}}}|
    {{角色详细信息|{{{名字}}}}}
|}}
</syntaxhighlight>

'''3. 减少 #ask 查询'''

SMW 查询比较慢，尽量减少使用：
* ❌ 在每个角色页面都查询全部角色
* ✅ 在主页查询一次，分类页面使用分类系统
</div>

=== 🔐 数据验证 ===

在模板中验证输入数据：

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

=== 🌍 国际化支持 ===

如果需要多语言支持：

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

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

----

== 第九章：常见问题 ==

=== ❓ FAQ ===

<div style="margin: 20px 0;">

'''Q: Lua 模块报错怎么办？'''

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

----

'''Q: 模板显示不正常？'''

A: 可能的原因：
# 参数名拼写错误（区分大小写）
# HTML/CSS 语法错误
# 使用浏览器开发者工具检查

----

'''Q: SMW 属性没有存储？'''

A: 确保：
# 使用了 `{{#set:}}` 或 `[[属性::值]]`
# 属性名没有特殊字符
# 页面已保存（预览模式不会存储）
# 运行了 SMW 刷新任务

----

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

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

</div>

----

== 第十章：扩展建议 ==

=== 🚀 如何扩展这个系统？ ===

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 20px 0;">

<div style="background: #fff5f8; padding: 20px; border-radius: 10px; border: 2px solid #ff6699;">
<div style="font-size: 18px; font-weight: bold; color: #ff6699; margin-bottom: 10px;">💝 角色系统</div>
* 添加更多角色属性（星座、MBTI）
* 实现角色关系图谱
* 角色好感度历史记录
* 角色语音资料库
</div>

<div style="background: #e3f2fd; padding: 20px; border-radius: 10px; border: 2px solid #1976d2;">
<div style="font-size: 18px; font-weight: bold; color: #1976d2; margin-bottom: 10px;">📖 事件系统</div>
* 事件分支系统（选择影响后续）
* 事件触发条件（时间、地点、好感度）
* CG 图片展示
* 事件回放系统
</div>

<div style="background: #f0fff0; padding: 20px; border-radius: 10px; border: 2px solid #66dd88;">
<div style="font-size: 18px; font-weight: bold; color: #66dd88; margin-bottom: 10px;">🎮 游戏系统</div>
* 物品系统（礼物、道具）
* 成就系统
* 存档系统
* 小游戏集成
</div>

<div style="background: #fff3cd; padding: 20px; border-radius: 10px; border: 2px solid #ffc107;">
<div style="font-size: 18px; font-weight: bold; color: #f57c00; margin-bottom: 10px;">🌍 世界观</div>
* 地图系统
* 时间线系统
* 设定集
* 官方小说/漫画
</div>

</div>

----

== 总结 ==

<div style="background: linear-gradient(135deg, #ff6699 0%, #ff9966 100%); color: white; padding: 30px; border-radius: 15px; margin: 30px 0; text-align: center;">
<div style="font-size: 2em; font-weight: bold; margin-bottom: 15px;">🎉 恭喜你完成教程！</div>
<div style="font-size: 1.2em; line-height: 1.8;">
现在你已经掌握了使用 MediaWiki 构建二次元世界观的全部技能！<br/>
是时候创建属于你自己的幻想世界了！
</div>
</div>

=== 📚 相关资源 ===

* [[星之丘物语|返回主页]]
* [[Module:Affection|查看好感度系统源码]]
* [[单元测试|查看测试结果]]
* [[樱井明日香|角色页面示例]]
* [[图书馆的邂逅|事件页面示例]]

=== 🤝 参与贡献 ===

如果你有任何改进建议或发现问题，欢迎：
* 💬 在讨论页留言
* 🐛 报告 Bug
* ✨ 提交新功能建议
* 📝 完善文档

<div style="text-align: center; margin: 40px 0; padding: 30px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; border-radius: 15px;">
<div style="font-size: 2em; margin-bottom: 10px;">✨ 开始你的创作之旅吧！✨</div>
<div style="font-size: 1.2em; opacity: 0.9;">
MediaWiki + 你的想象力 = 无限可能
</div>
</div>

[[Category:教程]]
[[Category:开发文档]]
[[Category:新手指南]]