diff --git a/docs.md b/docs.md index 6101265..6bbb537 100644 --- a/docs.md +++ b/docs.md @@ -2,17 +2,17 @@ sqrtools 的接口调用指南。 -当前 API 版本:**2** +当前 API 版本:**3** ------ #### 在代码中添加 sqrtools -[sqrtools 网页](https://sqrt2802.pages.dev/sqrtools/)提供的的 pyc 文件可以作为 python 库文件使用。把它和你的代码放在同一个文件夹(也可以是 `sys.path` 中的任意目录)中,并直接在你的代码中导入即可: +[sqrtools 网页](https://sqrt2802.pages.dev/sqrtools/)提供的的 pyc 文件可以作为 python 库文件使用。把它和你的代码放在同一个文件夹(也可以是 `sys.path` 中的任意目录)中,使用一个合适的文件名,并直接在你的代码中导入即可: ```python -import sqrtoolsfile as sqrtools #导入 sqrtoolsfile.pyc 文件 -my_awesome_name=sqrtools.Name() #创建一个新的空白名字 +import sqrtoolsfile as sqrtools #导入名为 sqrtoolsfile.pyc 的文件 +my_awesome_name=sqrtools.Name() #创建一个新的空白名字 ``` 你可以通过 `sqrtools.SQRTOOLS_API_VERSION` 来查看接口版本。本篇文档适用的版本号已在开始处声明,你需要寻找一个与你的 sqrtools 适配的文档。 @@ -23,11 +23,11 @@ sqrtools 的主要功能是名为 `Name` 的 python 类。 `Name` 中包含以下数值: -- `val`, `namebase` : 使用字符串生成的 hash-like 数组,在其他算号器中可能被称为 `name_base` 等。`val` 长度为 256,`namebase` 长度为 128。 +- `val`, `namebase` : 使用字符串生成的 int 数组,在其他算号器中可能被称为 `name_base` 等。`val` 长度为 256, `namebase` 长度为 128。 -- `nameprop` : 名字属性,也就是俗称的"八围"。是长度为 8 的数组,从前到后分别为 \[攻, 防, 速, 敏, 魔, 抗, 智, HP\] 数值。 +- `nameprop` : 名字属性,也就是俗称的"八围"。是长度为 8 的 int 数组,从前到后分别为 \[HP, 攻, 防, 速, 敏, 魔, 抗, 智\] 数值。 -- `nameskill` : 存储名字技能的数组,由 40 个形如 (id, 熟练度) 的二元组组成。技能 id 与名称的对应关系如下: +- `nameskill` : 存储名字技能的 int 数组,由 40 个形如 (id, 熟练度) 的二元组组成。技能 id 与名称的对应关系如下: id|0|1|2|3|4|5|6|7|8|9| :-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-: @@ -41,12 +41,14 @@ id|0|1|2|3|4|5|6|7|8|9| #### Name 类型方法 -使用 `Name()` 可以创建一个新的空白名字。一个 `Name` 类型理论上可以重复使用,但我们不推荐这样做。 +使用 `Name()` 可以创建一个新的空白名字。一个类型为 `Name` 的变量**不可以重复使用**。如果你想对同一个 Name 变量多次载入不同的名字,需要使用 reusable 模式,文档后面的部分有详细介绍。 -在开始计算前,你需要使用 `check()` 方法将名字以字符串参数的形式传入。此函数会返回一个数值,代表操作的完成状态: +在开始计算前,你需要使用 `check()` 方法将名字以字符串参数的形式传入。此函数会返回一个 int 数值,代表操作的完成状态: - 0: 名字成功载入。 +- 1: 对已加载的名字变量重复载入,操作失败。 + - -1: 输入了空的字符串,载入失败。 - -2: 无法分割名字与战队名(可能是因为输入了过多的 @ 符号),载入失败。 @@ -55,13 +57,13 @@ id|0|1|2|3|4|5|6|7|8|9| `Name` 类型包含以下用于算号的函数方法: -- `load()` : 计算 `val` 和 `namebase`。 +- `load()` : 计算 `val` 和 `namebase`。该操作只能进行一次。 - `calcprops()` : 计算名字属性,执行前需要先使用 `load()`。 -- `calcskill()` : 计算名字技能,执行前需要先使用 `load()`。 +- `calcskill()` : 计算名字技能,执行前需要先使用 `load()`。算技能操作只能进行一次。 -需要注意的是,以上函数均不会返回任何信息。计算完成后,你需要手动调用相关的属性变量查看结果。 +计算完成后,你需要手动调用 Name 变量下相关的属性数组查看结果。 以下是一个计算名字数值属性的示例程序: @@ -71,8 +73,18 @@ name=sqrtools.Name() name.check('1') name.load() name.calcprops() -print(name.nameprop[7],end=' ') #HP -for i in range(7): #七围 - print(name.nameprop[i],end=' ') -print() -``` \ No newline at end of file +print(name.nameprop) +``` + +#### 名字加载锁与 Reusable 模式 + +`Name` 名字的加载过程是单向且不可重复的。如果你试图对未执行 `load()` 的名字算属性/技能,对名字重复载入、`load()` 和 `calcskill()`,或进行其他非法操作,那么你使用的函数将拒绝操作并返回 `False`。`Name` 类型表现的这种行为在下文中简称为**名字加载锁**。 + +如果你想重复加载名字,可以在操作前将名字的 `reusable` 属性设置为 `True` 以启用 Reusable 模式。例如: + +```python +name=sqrtools.Name() +name.reusable=True +``` + +Reusable 模式允许你重复使用一个 `Name` 变量,但名字加载锁仍然存在,非法操作会被自动阻止。在你对变量载入新的字符串后,名字加载锁会重置。