# 中三G3华文论证冒险：远亲不如近邻 × 沟通面面观
### Secondary 3 (G3) Chinese Argumentation Adventure

> 这份 README 的每一段都有中英文两种版本。网页版还可以一键切换「华文／双语／English」。
> Every section of this README appears in both languages. The web version also has a 华文 / Bilingual / English switch.

**▶ 打开这里 ｜ Start here:** https://kaixinbuilds.github.io/S3G3CLArgumentativeAdventure/

---

## 这是什么 ｜ What this is

一款马里奥风格的 HTML5 平台游戏，帮助中三 G3（普通程度）学生辨识两篇华文课文里的**论证法**。由一位华文老师主要透过与 Claude（Anthropic）对话完成，**不需要任何编程基础**。这个 repo 公开出来，是为了让其他老师看清楚整件事怎么做出来，并且能改成自己的课文。

A Mario-style HTML5 platformer that teaches Secondary 3 (G3 / lower-readiness) students to identify argumentation techniques (论证法) in two Chinese Language texts. It was built by a Chinese Language teacher, mostly through conversation with Claude (Anthropic), with **no prior coding background**. This repo exists so other teachers can see exactly how it was done and adapt it for their own texts.

---

## 落地页有两道门 ｜ The landing page has two doors

打开网址，老师和学生看到的是同一个入口，但走向不同的地方：

Teachers and students land on the same page and go different ways from there:

| 门 ｜ Door | 给谁 ｜ For | 内容 ｜ What it does |
|---|---|---|
| 🎮 **玩游戏 ｜ Play the game** | 学生 ｜ Students | 直接进入游戏（`game.html`）｜ Straight into the game (`game.html`) |
| 🛠️ **建游戏 ｜ Build your own** | 老师 ｜ Teachers | 三条分层路径，按各自的专业发展目标选 ｜ Three differentiated paths, chosen by your own PD goal |

要让学生直接进游戏，网址后面加上 `game.html` 即可。
To send students straight into the game, add `game.html` to the end of the address.

### 三条路径 ｜ The three paths

| 路径 ｜ Path | 做什么 ｜ What you do |
|---|---|
| 🚀 [原样拿去用 ｜ Use it as it is](tasks/1-use-as-is.html) | 开 GitHub 账号、复制 repo、开启 Pages，拿到自己的网址；要记分的话，下载压好的 `unit34sls.zip` 上传 SLS ｜ Create an account, fork, switch on Pages, get your own URL; for marks, download the ready-made `unit34sls.zip` and upload it to SLS |
| 🎨 [换角色美术 ｜ Change the artwork](tasks/2-change-art.html) | 用 AI 画五个动作的新角色，交给 AI 合成贴图并换进游戏 ｜ Generate a five-pose character with AI, then let the AI stitch and swap the sheet |
| ✍️ [换成自己的课文 ｜ Put your own text in it](tasks/3-change-questions.html) | 在 Excel 题库里改题目，交给 AI 生成新版本 ｜ Rewrite the questions in the Excel workbook and let the AI rebuild the game |

三条路径都**不需要看懂任何一行程序码**，页面上可以直接下载所需档案、一键复制给 AI 的提示语。

None of the three paths requires **reading a single line of code**. Each page has the files to download and the AI prompts ready to copy with one click.

---

## 两个游戏版本 ｜ Two builds of the game

| | `game.html` | `sls/index.html` |
|---|---|---|
| **用在哪里**<br>**Where it runs** | 任何网站 / GitHub Pages<br>Any website / GitHub Pages | SLS Interactive Response |
| **学生怎么进入**<br>**How students open it** | 点一个网址，免登录<br>One link, no login | SLS 课业里点开<br>From an SLS assignment |
| **分数进不进教师后台**<br>**Scores in the teacher's gradebook** | ❌ 不会 —— 学生只在画面上看到自己的分数<br>❌ No — students only see their own score on screen | ✅ 会 —— 每位学生的分数自动送进 SLS 教师后台 Gradebook，老师不必手动改分<br>✅ Yes — every score lands in the SLS gradebook automatically, nothing to mark |
| **内含 xAPI wrapper**<br>**Contains the xAPI wrapper** | 否，已完全移除<br>No, fully removed | 是，内嵌 xAPIWrapper v1.11.0<br>Yes, xAPIWrapper v1.11.0 embedded inline |
| **怎么部署**<br>**How to deploy** | Settings → Pages | 下载 `unit34sls.zip` 直接上传（已压好）｜ Upload `unit34sls.zip` as downloaded (already packaged) |
| **上传成哪种元件**<br>**Which component type** | 不适用 ｜ N/A | ⚠️ **Question → Free Response → Interactive Response**。选成 Text/Media，游戏照玩，但**分数一分都记不到**，而且当下看不出来<br>⚠️ **Question → Free Response → Interactive Response.** Choose Text/Media and the game still plays but **not a single mark is recorded**, with nothing on screen to show it |

**两版的游戏内容、题目、计分、生命值、结束评语完全相同** —— 差别只在于分数会不会送回 SLS。

Both builds are identical in content, questions, scoring, lives and closing feedback — the only difference is whether scores are reported back to SLS.

---

## 游戏内容 ｜ What's in the game

- **20 道题**，分 2 关（每关 10 题）：三选一选择题 + 1 道配对题
  第一关 —— 《远亲不如近邻》（单元三复习）：举例论证法、引用论证法
  第二关 —— 《沟通面面观》（单元四预习）：多方面论证
- **5 条生命**（一般游戏只给 3 条）—— 刻意放宽的容错空间，让普通程度的学生不会因为频频重来而放弃
- 角色穿的是**本校运动服**，五个动作：站立、走路、跳跃、摔落
- **校色介面**（蓝 · 绿 · 黄）+ **三层视差山峦背景**
- **音效与背景音乐全部以 Web Audio 即时合成**，没有任何外部音档：档案不变大、SLS sandbox 也能响，也不牵涉音乐版权
  - BGM 是 8 小节 chiptune 循环，**答题时自动压低音量**，方便学生读题
  - 控制列右下角：**🔊 总开关**、**🎵 只关音乐**，选择会记住 —— 课堂上不必担心二十台 iPad 一起吵
- 手机 / iPad / 电脑都能玩（画面下方有 ◀ ▶ 跳！三个触控按钮）
- **单一自足的 HTML 档案**：纯 JavaScript + HTML5 Canvas，不需要建置工具，角色贴图以 base64 内嵌，离线也能玩

<br>

- **20 questions** across 2 levels (10 each): three-option MCQs plus one matching question
  Level 1 — 《远亲不如近邻》 (Unit 3 revision): 举例论证法, 引用论证法
  Level 2 — 《沟通面面观》 (Unit 4 preview): 多方面论证
- **5 lives** instead of the usual 3 — a deliberate accommodation so lower-readiness students finish without frustration
- A custom character in the **school PE uniform**, with five poses: stand, walk, jump, fall
- **School-colour interface** (blue · green · yellow) and a **three-layer parallax mountain background**
- **Sound effects and music synthesised live in Web Audio** — no audio files at all: nothing bloats the file, it plays inside the SLS sandbox, and no music copyright is involved
  - The BGM is an 8-bar chiptune loop that **ducks automatically while a question is open**
  - Bottom right of the control bar: **🔊 mute everything**, **🎵 music only**; the choice is remembered, so twenty iPads won't blare at once
- Plays on phone, iPad and computer (◀ ▶ 跳！ touch buttons sit below the canvas)
- **画面随窗口大小自动铺满**，投影或全屏时人物与山峦一起放大；控制列右下角有 **⛶ 全屏**按钮
  **The view fills the whole window**, rescaling live as the window resizes — handy on a projector; a **⛶ fullscreen** button sits at the bottom right
- **A single self-contained HTML file**: vanilla JavaScript + HTML5 Canvas, no build tools, sprite embedded as base64, works offline

---

## 改成自己的课文（工作坊任务）｜ Adapt it to your own text (workshop task)

**最省事的做法：走[路径 3](tasks/3-change-questions.html)** —— 下载已经填好 20 题的 Excel 题库，把内容换成你的课文，连同 `game.html` 一起上传给 Claude 或 ChatGPT，贴上页面上准备好的提示语，AI 会把新版本做好给你下载。

**The easiest route is [Path 3](tasks/3-change-questions.html):** download the Excel workbook (already filled with the current 20 questions), replace the content with your own, upload it together with `game.html` to Claude or ChatGPT, paste the ready-made prompt, and the AI hands you the finished file.

📊 [下载题库模板 ｜ Download the question workbook](docs/question-bank-template.xlsx)

### 想直接改程序码的话 ｜ If you'd rather edit the code directly

所有题目都在 `game.html` 里的 **`QS` 数组**（约第 231 行，注释写着 `QUESTION DATA`）。在 GitHub 网页上点开档案 → 右上角铅笔 ✏️ → 改完按 **Commit changes**，Pages 一两分钟后自动更新。

All questions live in the **`QS` array** inside `game.html` (around line 231, under the comment `QUESTION DATA`). On the GitHub website: open the file → pencil ✏️ at the top right → edit → **Commit changes**. Pages updates itself within a minute or two.

```javascript
// 选择题 ｜ multiple choice
{type:'mcq',
 logic:'📌 论点：…',        // 论点框，可整行省略 ｜ claim box, whole line optional
 ext:'「课文摘录……」',       // 引文框，可整行省略 ｜ quoted passage, whole line optional
 t:'题干？',                // 题干 ｜ question stem
 o:['选项A','选项B','选项C'], // 三个选项 ｜ the three options
 a:0,                       // 正确答案：0=第一个 ｜ correct answer: 0 = first
 e:'✅ 正确！…'},            // 答后解释 ｜ explanation after answering

// 配对题 ｜ matching
{type:'match',
 t:'将下面四段论据，配对到正确的论证法：',
 items:[{text:'…', c:0},{text:'…', c:1}],   // c = 类别编号 ｜ index of the category
 cats:['举例论证法','引用论证法'],             // 类别按钮，2–3 个最好看 ｜ 2–3 buttons looks best
 e:'✅ …'},                                 // 配对全对才得 1 分 ｜ full match only scores
```

### 其他常改的地方 ｜ Other things people commonly change

| 想改什么 ｜ What to change | 改哪里 ｜ Where | 行数 ｜ Line |
|---|---|---|
| 浏览器分页标题 ｜ Browser tab title | `<title>…</title>` | 22 |
| 游戏标题 ｜ Game title bar | `<div id="titleBar"><h1>…</h1></div>` | 167 |
| 题目内容 ｜ The questions | `const QS=[…]` | 231 |
| 关卡名称 ｜ Level names | `const LVNAMES=[…]` | 355 |
| 每关题目范围 ｜ Questions per level | `const LV_Q=[[0,9],[10,19]]` | 356 |
| 音效 ｜ Sound effects | `const SFX={…}` | 363 |
| 背景音乐 ｜ Background music | `const BGM={…}`（`mel`／`bass` 每 8 个数字一小节 ｜ 8 numbers per bar） | 408 |
| 生命数（预设 5）｜ Number of lives (default 5) | `const G={… lives:5 …}`，另见三处 `G.lives=5` ｜ plus the three `G.lives=5` | 482 |
| 天空 / 地面 / 山峦配色 ｜ Sky, ground and mountain colours | `const TH=[…]` | 536 |
| 贴图帧数与姿势顺序 ｜ Frame count and pose order | `const NFR=5,FR={…}` | 608 |
| 角色 sprite ｜ Character sprite | `sprite.src='data:image/png;base64,…'`（五帧 ｜ 5 frames） | 612 |
| 视差速度 ｜ Parallax speed | `function drawMountains()` | 632 |
| 角色大小 ｜ Character size | `const DRAW_H=74` | 712 |
| 过关说明与评语 ｜ Level-clear text and feedback | `function lvDone()` | 909 |
| 开场说明 ｜ Opening screen | 档案最后的 `showScr('⚔️', …)` ｜ the `showScr('⚔️', …)` near the end | 978 |
| 介面配色 ｜ Interface colours | `<style>` 区块 ｜ the `<style>` block | 23–163 |

> 行数以 `game.html` 为准；`sls/index.html` 因为多了 xAPI 程序码，行数会往后挪。
> Line numbers refer to `game.html`; everything shifts down in `sls/index.html` because of the extra xAPI code.

### 改题时的注意事项 ｜ Things to watch when editing questions

- **保持 20 题最省事**。题数一改，`LV_Q` 和 `buildLv()` 里的方块座标 `bd` 数组也要跟着改（方块数量 = 每关题数）。
- **选项长度尽量一致**，避免学生靠「哪个最长」猜答案。
- 中文引号用 `「」`；字串里要用单引号 `'` 请写成 `\'`。每题的 `{...}` 之间别漏了逗号。
- **改完自己从头玩一遍**：20 题都能开、配对题能提交、分数与生命正常、三档评语合理、iPad 上按钮灵敏。
- 画面卡在开场 = 多半是 `QS` 少了逗号或引号没关好。按 F12 → Console 看红字。

<br>

- **Keeping 20 questions is the least work.** Change the count and you must also update `LV_Q` and the `bd` coordinate array in `buildLv()` (blocks per level = questions per level).
- **Keep the options similar in length**, so students can't guess by picking the longest.
- Use `「」` for Chinese quotation marks; a single quote inside a string must be written `\'`. Don't drop the comma between questions.
- **Play the whole thing through after editing:** all 20 questions open, the matching question submits, score and lives behave, all three feedback bands make sense, buttons respond on iPad.
- Stuck on the opening screen = almost always a missing comma or unclosed quote in `QS`. Press F12 → Console.

---

## 档案结构 ｜ Repo structure

```
├── index.html                     ← 落地页：两道门 ｜ Landing page: the two doors
├── game.html                      ← 游戏（网站版，无 xAPI）｜ The game (web build, no xAPI)
├── sls/index.html                 ← 游戏（SLS 版，自动记分）｜ The game (SLS build, auto-scoring)
├── unit34sls.zip                  ← 上传 SLS 就是这个（已压好）｜ The file you upload to SLS (already packaged)
├── tasks/                         ← 老师的三条路径（可直接下载档案、复制提示语）
│   │                                The three teacher paths (downloads and copyable prompts)
│   ├── 1-use-as-is.html
│   ├── 2-change-art.html
│   └── 3-change-questions.html
├── assets/                        ← 页面样式、语言切换、角色贴图 ｜ Page styling, language switch, sprite sheet
├── tools/
│   └── pack-sls.py                 ← 改过 SLS 版之后重打 zip ｜ Repackages the zip after editing the SLS build
├── docs/
│   ├── question-bank-template.xlsx ← 已填好 20 题的题库模板 ｜ The prefilled question workbook
│   ├── 创作思路.md                  ← 教学设计的思路 ｜ The pedagogical thinking
│   ├── xapi-scoring-wrapper.md     ← 自动记分的原理 ｜ How the auto-scoring works
│   ├── sls-deployment.md           ← 下载、上传、确认分数 ｜ Download, upload, verify scores
│   ├── sprite-pipeline.md          ← 角色贴图怎么做 ｜ How the sprite was made
│   └── rebuild-guide.md            ← 自己重做一版的技术规格 ｜ Spec for rebuilding from scratch
└── LICENSE                        ← MIT
```

---

## 制作与致谢 ｜ Credits & inspiration

游戏设计与内容：**郑凯欣老师** · 百德中学母语部主任
Game design and content: **Mdm Chun Kai Xin** · HOD/MTL · Bukit View Secondary School

本游戏模式可自由复制、改编，欢迎标注原创来源。
This game format may be freely copied and adapted; a credit back to the original is appreciated.

这个项目的直接灵感来自 **Kiren Gill 老师**（义顺小学）在 SgLDC 社群分享的 SLS Interactive 语文游戏帖子，让人想到：*华文的论证能力，是不是也能这样教？*

This project was directly inspired by **Kiren Gill** (Yishun Primary), whose post in the SgLDC community about using SLS Interactive for language games sparked the idea: *could this work for Chinese argumentation skills too?*

使用的工具 ｜ Built with:

- **Claude** (Anthropic) — 游戏设计、程序码、全部文件 ｜ game design, code, all documentation
- **ChatGPT Image** — 像素角色贴图 ｜ pixel-art sprite generation
- **[xAPIWrapper v1.11.0](https://github.com/adlnet/xAPIWrapper)** (ADL) — 内嵌于 SLS 版，负责回报分数 ｜ embedded in the SLS build for score reporting

坦白说：这是一位不会编程的老师，在 AI 协助下做出来的。如果你是老师，正在想「我肯定做不出这种东西」—— 你想错了，这个 repo 就是证明。拿去改、拿去玩坏，记得注明来源，也请把你做出来的东西分享出来。

Full transparency: this is an AI-assisted build from a non-programmer teacher. If you're a teacher reading this and thinking "I could never build something like this" — you're wrong, and this repo is the proof. Adapt it, break it, credit where it's due, and please share what you build.

---

## SLS 社群资源库 ｜ SLS Community Gallery

已上架的课业（需登录 SLS）｜ Published module (requires SLS login):
https://vle.learning.moe.edu.sg/community-gallery/module/view/27dc152e-8807-4135-9d6f-e9325449c01e

## 授权 ｜ License

MIT 授权 —— 见 [LICENSE](LICENSE)。欢迎使用、改编，拿去教学。
MIT — see [LICENSE](LICENSE). Use it, adapt it, teach with it.