# 自动记分的原理（xAPI wrapper）｜ How the auto-scoring works
> **不必看懂这一页也能用。** 这是给想知道「分数为什么会自己跑进教师后台」的人看的。只想部署的话，看 [sls-deployment.md](sls-deployment.md) 就够了。
>
> **You don't need this page to use the game.** It's here for anyone curious about *why* the score lands in the gradebook by itself. If you just want to deploy, [sls-deployment.md](sls-deployment.md) is enough.
大多数老师卡住的就是这一关。SLS 会不会自动把分数记进 gradebook，**取决于**你的 HTML5 课业有没有用一个叫 **xAPI**（Experience API，又称 Tin Can）的标准跟 SLS 讲话。这份文件说明这个游戏是怎么接上去的，你可以照抄到自己的课业里。
This is the part most teachers get stuck on. SLS can auto-record a score in the gradebook **only if** your HTML5 activity talks to SLS using a standard called **xAPI** (Experience API / "Tin Can"). This doc explains exactly how that's wired up in this game, so you can copy the pattern into your own activity.
## 它解决了什么问题 ｜ The problem this solves
没有它的话，SLS 上的 HTML5 游戏要「算分」，只能叫学生截图上传当凭证 —— 多数老师自制的游戏就是这样做的，两边都麻烦。内嵌了 xAPI wrapper 之后，**学生一做完，分数就自动送出**，直接出现在教师的 **Learning Progress** 里。不必截图，不必人工核对。
Without this, the only way to "grade" an SLS HTML5 game is to make students screenshot their result and upload it as proof — which is what most teacher-made games do, and it's a pain for everyone. With the xAPI wrapper embedded, **the score is sent automatically the moment the student finishes**, and it shows up in the teacher's **Learning Progress** view. No screenshots, no manual checking.
## 为什么整个程式库都得内嵌 ｜ Why it has to be embedded inline
SLS 把上传的 HTML5 内容放进一个 sandbox iframe 里执行，那里**挡掉所有对外的网络请求** —— 不能载 CDN 脚本，不能用外部 `
```
## 游戏里怎么呼叫它 ｜ How to call it from your game logic
通常两个地方 ｜ Two places, typically:
```javascript
// 1. Optional checkpoint — e.g. after level 1 finishes
XAPIUtils.sendScore(G.sc, 20); // (currentScore, maxPossibleScore)
// 2. Required — when the whole game/activity is completed
XAPIUtils.sendScore(G.sc, 20);
```
`G.sc` 只是这个游戏用来记分的变量，换成你自己程式里的名称即可。
`G.sc` here is just whatever variable your game uses to track the running score — rename it to match your own code.
## 一定会踩到的坑 ｜ Gotchas that will bite you
| 状况 ｜ Issue | 怎么办 ｜ Fix |
|---|---|
| 后台分数是空的
Score shows blank in the gradebook | 元件**必须**用 **Interactive Response** 上传，不能用 Text/Media（见 [sls-deployment.md](sls-deployment.md)）
The component **must** be uploaded as **Interactive Response**, not Text/Media |
| 分数卡在 99 上不去
Score caps at 99 | SLS 对 Interactive Response 的 **Maximum Marks** 硬性上限就是 99 —— 请重新设计配分（例如每题 1 分 × 20 题 = 20 分），而不是每题 10 分
That's SLS's hard limit — recalibrate your scoring (1 mark × 20 questions = 20) rather than 10 marks per question |
| 什么都没发生，也没有错误讯息
Nothing happens, no console errors | 确认你是在 SLS *里面*测试。在本机浏览器打开时，网址里没有 `endpoint` 参数，`init()` 会安静跳过 —— 这是正常行为，不是坏了
Check you're testing *inside* SLS; opened locally there's no `endpoint` parameter, so `init()` silently skips — expected, not a bug |
| 分数送出了，老师却看不到
Score submitted but the teacher can't see it | 确认 SLS 元件里的 **Maximum Marks** 真的设了（不是留在预设的 0）
Confirm **Maximum Marks** was actually set on the component, not left at 0 |
## 搬到自己的游戏里 ｜ Adapting this for your own game
不必看懂 xAPI 的内部机制也能重用。整个模式就三步：
1. 把上面两段 `