TTS官方API翻译(连载)

虽然想接着130佬的帖子写点教学贴,但是想了想发现还是应该先把API这一块搞明白了,遂发本贴。

科普环节:
API(Application Programming Interface,应用程序接口)是一些预先定义的接口(如函数、HTTP接口),或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程,而又无需访问源码,或理解内部工作机制的细节。

对于有编程经验的人来说,能弄明白API,加上一些简单的Lua语言知识,(加上四处抄代码)就能够进行脚本编写,为mod添加自己想要的功能了。

自己渣翻,欢迎各位大佬指导改正。

以下正文
——————————————————-
介绍
在本节中,您将了解有关Tabletop Simulator的Lua脚本的所有事件/类/函数的详细信息。关于Lua脚本语言如何工作的更多信息,您可以查看Lua官方文档

TTS常用名词
物体(Object)
表示在游戏中存在的某一特定物体。如果某个物体被放入了袋子/卡组/……等容器中,直到它再次被从容器中取出为止,不视为在游戏中存在。
玩家(Player)
指参加游戏的一位玩家。游戏中的每位玩家与一种颜色对应,观察者玩家对应灰色(Grey)。如果你需要特定某一位玩家,应该使用该玩家所对应的颜色。
全局脚本(Global Script)
全局脚本指不依附于某一特定物体的脚本。这种脚本在游戏中将常态生效。
物体脚本(Object Script)
物体脚本指绑定在某一游戏中存在的特定物体,并作为该物体的一部分进行存储的脚本。与物体尺寸(scale)或颜色(tint)等属性相似,它也是物体的属性之一。某些函数(function)在执行时要求对象引用。在这种情况下,Global也是一种有效的对象引用。
GUID
在Tabletop Simulator中,GUID是用于表示特定游戏内物体的6位字符串。当物体在游戏中存在时,会自动进行GUID的分配。
进行物体复制时,在游戏引擎为新生成的物体分配新的GUID前,可能会出现有大约1帧的时间内原物体和新物体具有相同的GUID的情况。以此方法生成的,容器(袋子、卡组等)中的物体不会自动获得新的GUID,除非将这些物体移出容器使它们在游戏中存在。
注意:自定义卡组中卡的GUID
当你首次生成一个自定义卡组时,卡组中的每张卡共享一个相同的GUID。如果你需要获得不同的GUID来区别每张卡,那么解决方法是将这些卡同时摆放在桌面上,以使游戏为其分配不同的GUID。这个工具可以简化这一过程。

已废弃的API(Deprecated APIs)
在本文档中,你可能会遇到标记为<deprecated>的Lua API。建议您不再使用标注为已废弃的API。通常,这是因为引入了更新/更好的API,能够更加有效地完成同样的功能。
已废弃的API不会被移除或停止使用。
现存的mod可以继续使用已废弃的API,但是我们强烈建议您在编写新的脚本时,为了更好的使用效果,避免使用已废弃的API。

类(Class)
对类的定义需要进一步的面向对象编程知识才能真正理解。但是,对于Tabletop Simulator 的Lua脚本,可以将类看作是同类物体的的标准或集合。
物体类(Object Classes)
与游戏中某类特定物体相关联。

  • 时钟(Clock)
  • 计数器(Counter)
  • 物体(Object)
  • 资源包(AssetBundle)
  • RPG模型(RPGFigurine)
  • 文字工具(TextTool)

静态类(Static Classes)
与游戏中某些属性或系统相关联。

  • JSON
  • 玩家(Player)
  • WebRequest
  • Physics
  • Lighting
  • Turns
  • Notes
  • UI
  • Wait

更多关于类的相关信息,可以参考相关的Lua文档

数据类型(Type)
数据类型表示信息的种类。在Lua语言中不需要进行类型的声明,不过在本API中会标出数据类型,以提示给定的变量或参数需要何种类型的数据。本API使用以下几种数据类型。
标准数据类型(Common Standards)

标签 种类 描述 例子
<nil> nil 空值 nil
<int> int 整数数值 5
<float> float 双精度浮点数 2.032
<bool> bool truefalse true
<string> string 一系列字符的组合 “Hello.”
<table> table 若干索引与值的关联数组 {[“key”]=”value”, true, 5}
<vector> vector Vector章节中详细描述
<color> color 在Color章节中详细描述
<func> function Function章节中详细描述
<object> object 游戏中存在的物理物体/全局对象 Global/self
<player> player 玩家 Player[“White”]
<var> variable 其他类型的组合

更多关于数据类型的相关信息,可以参考相关的Lua文档

特殊类型(Special Standards)
某些数据类型需要以特定的方式使用。Color和Vector类型是Tabletop Simulator中常用的表,用以表示颜色或向量,其内容在使用时必须遵循某种特定的格式。
Function类型一般在正在运行的脚本中因某种特定需求需要延迟时使用。
颜色(Color)
color类型是一种在定义物体颜色时用来表示RGB值的表。
Color的索引
color表会使用索引r,g,b,a和 /或1,2,3,4。字母和数字索引互为复制,每个索引代表一种颜色或透明度。

颜色 字母索引 数字索引
r 1
绿 g 2
b 3
透明度(alpha) a 4

举例来说,白色物体的颜色如下表:

  1. {
  2.     r=1, g=1, b=1,
  3.     1=1, 2=1, 3=1,
  4. }

复制代码

注意,该表不包括索引a或4。这是因为目前只有脚本按钮和脚本输入使用alpha通道(透明度)。
混合使用索引
使用索引时,同时只需要数字或字母其中一种索引。当表中同时有两种索引时,系统会忽略数字索引,使用字母索引。

  1. –Valid Table for red
  2. {r=1, g=0, b=0}
  3. –Valid Table for blue
  4. {0, 0, 1}
  5. –This Table would be red.
  6. {r=1, g=0, b=0, 0, 0, 1}

复制代码

Color的值
color表每个索引对应的取值范围为0-1之间。如果你使用的是0-255的RGB数值,你可以使用简单的数学公式进行转换。

  1. –To display a color that is r=50, b=83, g=199
  2. self.setColorTint({50/255, 83/255, 199/255})

复制代码

字符串
你也可以使用字符串代替color表。使用代表一种玩家颜色的字符串将自动转换为对应的颜色,在玩家颜色(Player Color)中提到的12种颜色名均可进行识别。例如:

  1. printToAll(“Test”, “Green”)

复制代码

向量(Vector)
向量是一种具有x、y和z坐标的对象,用于定义位置、旋转或方向。
你可以通过Vector类来操作向量。例如:

  1. target = Vector(1, 0, 0) + Vector(0, 2, 0):normalized()

复制代码

Vector的索引
表示向量的表包含字母索引x,y,z和/或数字索引1,2,3,字母与数字索引等价。

字母索引 数字索引
x 1
y 2
z 3

举例来说,坐标为X=5, Y=2, Z=-1的物体将返回如下的vector:

  1. {
  2.     x=5, y=2, z=-1,
  3. }

复制代码

混合使用索引
在引入vector类之前,坐标表在同时存在不同的数字索引与字母索引时,将优先使用字母索引。现在,这两种索引的优先级相同。不过,当使用pairs遍历vector的内容时,pairs只读取字母索引。
取值范围
vector各值的取值范围由vector的种类决定。

种类 描述 取值范围
位置 空间中的一点 任何合法位置取值
旋转 角度 -180到180
方向 方向向量 -1到1

种类细节
位置(Position)
X代表左右方向,Y代表上下方向,Z代表前后方向。位置向量可能是全局位置向量,代表全局位置;也可能是本地位置向量,代表与某物体的相对位置。大多数Tabletop Simulator的函数使用基于全局位置的向量。

种类 描述
全局 以桌面中心为{x=0, y=0, z=0}
本地 以物体模型的中心为{x=0, y=0, z=0}。模型的中心由模型的创建者决定。

使用positionToWorld(…)和positionToLocal(…) 函数可以进行两种类型之间的转换。

旋转(Rotation)
X代表俯仰方向旋转(点头),Y代表水平方向旋转(摇头),Z代表左右方向摇动(摆头)。
方向(Direction)
X代表左右方向,Y代表上下方向,Z代表前后方向。

函数(Function)
函数是触发时可以运行的一段代码。在Lua中,可以将函数作为参数传递。Tabletop Simulator中的某些元素可以通过函数来执行某些操作,例如在延迟后触发。
使用方法
在传递函数之前,首先需要定义函数。定义函数有以下几种方法:

  1. –Create it on-the-fly
  2. function() print(“Like This”) end
  3. –Create it with a variable name
  4. anyFuncName = function() print(“Like This”) end
  5. –Create it with a variable name that can also be passed parameters
  6. function anyFuncName(printString)
  7.     print(printString)
  8. end

复制代码

注意
在传递时,你需要传递函数本身而非函数的执行结果。因此以下的代码不会生效:

  1. Wait.frames(print(“Ding”), 80)

复制代码

为使之生效,你需要让print作为函数的执行结果:

  1. Wait.frames(function() print(“Ding”) end, 80)

复制代码

举例
举例来说,这里是Wait.frames(…)函数的三次调用。这个函数的作用是等待指定数量的帧之后执行给定的函数:

  1. function onLoad()
  2.     –Built-in functions with parameters can be called directly
  3.     –This is done by wrapping the function within `function()` and `end`
  4.     Wait.frames(function() print(“One”) end, 60)
  5.     –You can also call custom functions you have made yourself
  6.     –Pass them any parameters you wish
  7.     Wait.frames(function() sayTwo(“Two”) end, 120)
  8.     –If you aren’t passing any parameters to the function, you can shorten it
  9.     Wait.frames(sayThree, 180)
  10. end
  11. –Has its parameter passed to it
  12. function sayTwo(s) print(s) end
  13. –Does not have any parameters passed to it
  14. function sayThree() print(“Three”) end

复制代码

由于没搞懂论坛怎么做到这种效果(见下图),剩下的部分会改为用文档更新。 
任何人在本网站展示图片,应经合法权利人的授权,本网站只做形式上的审核。任何未经授权便在本网站上使用该图片都可能违反国际法,商标法,隐私权法,通讯、通信等法律法规。一经权利人提出异议,本网站在承担立即删除该信息义务外,不再承担其他任何法律责任。本网站上表述的任何意见均属于作者个人意见,并不代表爱桌游网及其管理者的意见。浏览者可以下载本网站上显示的资料,但这些资料只限用于个人学习研究使用,不得用于任何商业用途,无论是否在资料上明示,所有此等资料都是受到版权法的法律保护。浏览者没有获得版权所有者明确的书面同意下,不得分发、修改、散布、再使用、再传递或使用本网站的内容用于任何公众商业用途。
爱桌游 » TTS官方API翻译(连载)

发表评论