# gg

**Repository Path**: rmxp/gg

## Basic Information

- **Project Name**: gg
- **Description**: Gitbook Game
利用 gitbook 生成文字游戏的静态页面
- **Primary Language**: JavaScript
- **License**: CC0-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2018-03-12
- **Last Updated**: 2024-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitbook Game (gg)

## 安装 gitbook
首先需要在PC上安装 gitbook，步骤如下：

1. 安装 node.js 和 npm.
    1. 打开 cmd，输入 `node -v`，如果已经安装了会显示对应的版本
    2. 未安装，按照这个网站来做：[廖雪峰的官方网站](https://www.liaoxuefeng.com/wiki/001434446689867b27157e896e74d51a89c25cc8b43bdb3000/00143450141843488beddae2a1044cab5acb5125baf0882000)
2. 安装 gitbook-cli 和 gitbook.
    1. 打开 cmd，输入 `npm install -g gitbook-cli`
    2. 安装完毕后，输入 `gitbook -V`，查看安装情况，通常此时会自动安装 gitbook
3. 安装 sublime-text3，notepad++ 或者 MarkdownPad 用于编辑 .md 文件
    1. [sublime-text3](https://www.sublimetext.com/)
    2. [notepad++](https://notepad-plus-plus.org/)
    3. [MarkdownPad](http://markdownpad.com/)

## 文件夹
GitBook Game（简称gg）项目的结构如下：
```
|- LANGS.md
|- [src]
   |- img1.png
   |- script.js
|- [admin]
   |- README.md
   |- SUMMARY.md
   |- CHAPTER.md
|- [player-1]
   |- README.md
   |- SUMMARY.md
   |- CHAPTER.md
|- [player-2]
   |- README.md
   |- SUMMARY.md
   |- CHAPTER.md
```
在根目录下设置 LANGS.md，gitbook 会生成一个挑选语言的主页，在 gg 的设计中，这里用来选择玩家。
* 不要在 LANGS.md 里设置 src。src 只是用来堆放素材。

src 文件夹里用来放置图片和脚本，访问到上级文件夹用 `../`，这样设置图片或脚本的路径：
```markdown
![img1](../src/img1.png)
<script src="../src/script.js"></script>
```
每一个玩家看到的是不同的页面，需要单独设置。设置好所有的章节和 README.md，然后设置 SUMMARY.md。
* admin 也是一个玩家，推荐设置一个 admin 角色用于调试
* 也可以先设置 SUMMARY.md，在 cmd 中执行代码 `gitbook init` 生成子文件夹和文件内容
* 关于如何书写 markdown，以及设置 README.md，SUMMARY.md 请参照 gitbook 的指南

当一切设置完毕后，在根目录（LANGS.md所在的目录）执行以下代码：
```
gitbook serve
```
用浏览器访问 `localhost:4000` 即可开始调试。同时，gitbook 会在根目录下生成 `_book` 文件夹。
* `_book` 文件夹就是一个静态的站点，可以挂靠到各种静态网站托管平台。
* 如果电脑有外网IP，开启服务后，可以直接访问 IP:4000。
* 笔记本电脑可以开一个热点，让周围的手机访问 IP:4000。
* 同样也可以在 Android 手机上开启 http 服务。[前往豌豆荚](http://www.wandoujia.com/apps/com.arashdeep.simplehttpserverfree)

## 页面变量
每一个页面会绑定 1 个变量对象 $db，页面会在后台自动刷新以更新此变量的值。
- 变量是一个 Object 对象，其 value 通常是数字/字符串，或者由数字/字符串组成的**数组**
- 不同的页面可以绑定同一个变量，对此变量的修改会在服务端同步
- 变量的修改逻辑是基于本地数据，服务端只是负责缓存，无法保证原子性（几乎同时的修改可能会导致冲突）
- 不同的 checkcode 可以使相同的页面使用不同的变量，其原理就是简单的把 checkcode 写入到变量名中
- 提供了一些函数用来快速设置变量，也支持自定义函数

### 导入脚本
按照 gitbook 的规则书写 .md 文件生成的页面，会自动按照语言生成对应的网页。在网页的结尾引入 jQuery 和 gitbookgame.js。之后连接到服务器读取一个变量。
- jQuery 用的 bootstrap 的 cdn
- gitbookgame.js 在这个项目中下载
- 调用函数 `connect('游戏名/变量名', 刷新时间)`，其中游戏名不能含 `/`
- 第一次调用 connect 会询问 checkcode，使用相同的 checkcode 才会访问相同的变量
- checkcode 保存在 cookie 里，时间为 1 天，从而只需输入一次
```html
<script src="https://cdn.bootcss.com/jquery/3.3.1/jquery.min.js"></script>
<script src="../src/gitbookgame.js"></script>
<script>
    connect('game/admin', 3);
</script>
```
### 替换文本
引入了脚本后，在 md 文件中可以使用变量替换文本，格式是 `${key}` 会被替换成 `$db[key]` 的值
- 后台页面自动刷新 $db 后，会立刻更改当前的显示
- 当 `$db[key]` 是一个数组时，并不只是简单的替换
- 只会替换 1 次，不会迭代替换

|html标签|md格式|说明|
|:--:|:---|:---|
|`<p>`|`文本内容${key}`<br>`> 引用内容${key}`|在文本和引用中替换部分文本<br>当变量为一个数组时，会自动换行|
|`<li>`|`- 选项 1`<br>`- ${key}`<br>`- 列表结尾`|替换文本，对数字索引的有序列表依然有效<br>当变量为一个数组时，会自动生成新的列表项|
|`<td>`|表格书写格式见下|替换文本，当变量为一个数组时会自动生成新的格子并换行<br>换行时会自动判断列数变量为数组时必需独占一行<br>* 参见下面的代码块|
|`<a>`|`[引用内容${key}](链接地址)`|由于`<a>`标签一定在`<p, li, td>`标签里，引用内容和地址都会被替换<br>* 建议只替换显示的引用内容|
|`<img>`|`![说明文字](链接地址${key})`|由于`<img>`标签一定在`<p, li, td>`标签里，说明文字和链接地址都会被替换<br>当链接地址的第1个变量为数组时，会生成多个替换结果的图片，之后的变量会替换成文本|
- 表格书写格式如下
```markdown
|header1|header2|header3|
|:--:|:--:|:--:|
|content1|cont${key}ent2| - |
|${list}|
```

### 隐藏内容
markdown 中使用多个 `#` 来表示 html 中的 `<hi> i = 1..6`，gitbook 会设置 `#` 后面的内容 id。如此可以对整个文档的内容进行分节。当 `$db['_hide_']` 包含有一个小节的 id 时，此小节会隐藏。同时隐藏从这个小节开始，到下一个同级或者更高级的小节之间的全部内容。比如说，如果设置了 1.1 被隐藏，其随后的内容会全部隐藏，直到遇到下一个小节 1.2：
```markdown
# 1
## 1.1
(隐藏)
### 1.1.1
(隐藏)
### 1.1.2
(隐藏)
## 1.2
```
- `#` 与 id 之间可以有多个空格
- 修改了 `$db['_hide_']` 会立即刷新显示的内容

### 超链接调用函数
当超链接按照以下写法时，会自动替换成函数调用：
1. 链接地址以 `js:` 开头
2. 设置了不为 `""` 的 title

注意：
- 只在页面第一次加载的时候，更换超链接为函数调用，此时数据库尚未加载
- 只是单纯的替换双引号`""`为括号`()`，所以可以用 `,` 隔开参数，或者用 `'` 表示字符串
- 转换时会把 `\?` 替换成 `?`，其中 `?` 是任意字符
    - 因为有时候 markdown 要求某些字符以转义的形式出现。比如说 `)` 要写成 `\)`

```markdown
[链接名称](js:function "parameters")
-> javascript:function(parameters)
[链接名称](js:function "1, 'yes', true")
-> javascript:function(1, 'yes', true)
```

### 内置函数
内置了以下函数修改变量的值：

|函数名|参数|描述|
|:---|:---|:---|
|setCookie|c_name, value, expiredays|从 W3CSchool上 copy 的函数，可以设置本地的 cookie|
|getCookie|c_name|从 W3CSchool上 copy 的函数，可以获取本地的 cookie|
|set_checkcode|无|弹出一个输入框以获取新的 checkcode 并保存在 cookie里|
|connect|db_name, refresh_time=3|设置本页面连接的变量和刷新时间（秒）<br>如果 checkcode 没有设置，会先弹出一个对话框要求设置 checkcode|
|update|db_name, update_value, force='0'|直接修改任意的变量<br>update_value 会转化成 json 再传递到服务端<br>当 db_name 设置为 null 时，会指向本页面绑定的变量<br>当force 设置为 '0' 以外的值时，会以 update_value 的值替换此变量。|
|get|key|就是 $db[key]，获取本页面绑定的变量中的 key 对应的值，下面的函数都是针对本页面的变量|
|set|key, value|就是 $db[key] = value，多个几乎同时的设置，会使得后面的设置将前面的覆盖|
|add|key, value|在 key 对应的数组里添加单元<br>如果 key 不存在，则初始值是一个空数组<br>如果 value 是一个数组，会添加 value 中的每一项，而不是添加一个数组作为一个单元|
|del|key, value|在 key 对应的数组里移除值等于 value 的单元<br>如果 key 不存在，则初始值是一个空数组<br>如果 value 是一个数组，会移除值与 value 中的任意一个单元相同的项<br>* 可能移除多个单元|
|setif|key, value, condition|如果 condition 为真，则执行 set(key, value)<br>如果 condition 是一个无参数的函数，则获取返回值判断|
|addif|key, value, condition|同上，执行的是 add(key, value)|
|delif|key, value, condition|同上，执行的是 del(key, value)|
|input|prompt=""|就是 window.prompt(prompt, "")，弹出一个文字框，获取输入信息|
|p|text|就是 console.log(text)，调试用|
|refresh|无|周期性调用的刷新函数，从服务端获取数据，并且刷新页面中变量替换的内容|

## 服务器
服务器的代码详见 `gitbook.php`，其中的变量 `$url` 即为脚本放置的位置。

服务端利用 Memcached 服务存/取数据，但是只是使用了 set 和 get 两个方法。因为代码较简单，故可以自行修改。