TouchController 从入门到精通

支持版本

参见 #4

1.21.1 (NeoForge, Fabric)
1.21.10 (NeoForge, Fabric)
1.21.11 (NeoForge, Fabric)
26.1 (NeoForge, Fabric)
26.1.1 (NeoForge, Fabric)
26.1.2 (NeoForge, Fabric)
26.2 (NeoForge, Fabric)

支持平台

Windows（版本最低为 Windows 7，支持 x86、x86_64 和 ARM64 架构）
BlazeSDL
Linux Wayland（没有触控模拟鼠标支持，建议使用 BlazeSDL）
Fold Craft Launcher
Zalith Launcher
Zalith Launcher 2
Angel Aura Amethyst
Pojav Glow·Worm

下载

Important

请务必注意您的游戏版本和 mod 加载器，不要下载错误的版本。

请务必注意您使用的平台、游戏版本以及加载器是否支持 TouchController。

使用启动器下载

在模组安装页面中搜索 TouchController。
根据启动器的提示，根据安装到的 Minecraft 版本和 mod 加载器，寻找对应的最新版 TouchController。如果使用了 Fabric 版本，还需要安装 Fabric API 和 Fabric Language Kotlin，大部分启动器可以选择在安装游戏版本时一并安装 Fabric API，此时无需重复安装 Fabric API。
Fabric 版本还可以选择安装 Mod Menu，这样可以更方便地进入设置页面。

从网站下载

MCMOD | Modrinth | CurseForge | GitHub | Gitee

从上述网站下载正确版本的 TouchController。
找到 mod 文件夹，一般在 .minecraft/mods，如果开启了版本隔离，mod 文件夹就在 .minecraft/versions/<游戏版本名称>/mods。
将下载的 TouchController 模组文件放进去，如果使用了 Fabric 版本，还需要安装 Fabric API 和 Fabric Language Kotlin。

游玩

目前 GUI 内图层仍在开发中，关闭物品栏、呼出游戏菜单等 Escape 按键的功能可以由 Android 系统中的返回所替代。

隐藏启动器的控件

大部分启动器都有控件编辑功能，您可以删除启动器自带的控件。以 FCL 为例，您只需要新建一个空布局，删除原布局后进入游戏，便可以看到启动器自带的控件已被删除。

设置界面

您可以通过多种方法进入 TouchController 的设置界面。关于如何自定义设置，请参考设置界面及其子页面中的介绍。

通过模组菜单

打开模组菜单。如果使用 Fabric 加载器，需要安装模组菜单，Forge 加载器自带模组菜单。
在模组菜单中找到 TouchController，便可以进入设置页面。

通过游戏菜单

打开游戏菜单 -> 选项 -> 按键控制 -> 触摸设置。
一些版本进入方式可能有些许不同，但差别不会太大。

控件样式

概念

图集是对控件风格的分类，TouchController 目前拥有四种图集。
图标指的是控件中的图案，同样功能的控件可能有不同的图标；不同功能的控件一定有不同的图标，这些图标表达的含义也不相同。

图集

经典

英文名称：classic
描述：基岩版旧版贴图
经典图集是基岩版早期使用的贴图，也包括一些 TouchController 美术组补充的贴图，例如虚拟摇杆、疾跑、攻击、使用等等

新样式

英文名称：new
描述：基岩版新版贴图
新样式图集是基岩版目前正在使用的贴图，风格比较扁平化

经典扩展

英文名称：classic_extened
描述：新版图标和旧版控件背景
此图集全部贴图均由 TouchController 美术组绘制，但 TouchController 原创控件以及一些基岩版原版经典贴图所没有的控件贴图不在其中

新样式回归

英文名称：new_regression
描述：旧版图标和新版控件背景
此图集全部贴图均由 TouchController 美术组绘制，但 TouchController 原创控件以及一些基岩版原版经典贴图所没有的控件贴图不在其中

选择喜欢的布局

TouchController 拥有两种自定义布局模式，一种是预设模式，一种是自定义模式。预设模式只能切换一些选项，而自定义模式拥有极高的自由度，同时也更为复杂。

TouchController 会默认启用预设模式，也就是管理预设，此时进入自定义模式会出现一个弹窗，可以在弹窗中切换到自定义模式。此时进入预设模式会出现一个弹窗，可以在弹窗中切换到预设模式。

预设模式选项：

贴图风格

类型：单选列表
选项：
- 旧版贴图
- 旧版图标和新版控件背景
- 新版贴图
- 新版图标和旧版控件背景
参见控件样式

不透明度

类型：滑杆
默认值：60%
这个选项用来调整所有控件的不透明度，但物品栏按钮不受此选项影响。

大小

类型：滑杆
默认值：100
这个选项用来调整所有控件的大小，但物品栏按钮不受此选项影响。

自定义顶栏

类型：子页面
该页面可用于管理和排序顶栏控件，支持添加、删除、排序和预览。

控制方式

类型：单选列表
选项：
- 点击屏幕交互
- 使用准星瞄准
即：是否启用“分离控制”

通过按钮攻击与交互

类型：选项
前置：控制方式为“使用准星瞄准”
默认值：启用
启用后将关闭触摸手势，仅使用按钮攻击与交互。

移动方式

类型：单选列表
选项：
- 方向键
- 摇杆
此选项会导致下方选项产生一些差异

使用摇杆疾跑

类型：选项
前置：移动方式为“摇杆”
默认值：禁用
摇杆推到 110% 后触发疾跑。

交换跳跃与潜行

类型：选项
前置：
- 禁用“通过按钮攻击与交互”
- 移动方式为“方向键”
默认值：禁用

疾跑按键

类型：下拉菜单
选项：
- 无
- 右上角
- 右侧

使用原版聊天界面

类型：选项
默认值：禁用
控制聊天按钮是否打开 TouchController 的聊天界面

自定义布局

预设系统

在 v0.1.x 版本之前，预设系统只能做到保存与读取，不能进行编辑，与目前使用的布局相独立。但经过 v0.2.1 更新后，预设系统有了新的机制，可以做到不同布局之间的快捷切换，并且可以直接进行修改。

对布局的编辑必须使用一个预设，所有的编辑都在一个预设中进行。
TouchController 拥有一些内置预设，可以在创建预设时选择，或在预设模式下使用。
预设目前拥有三项设置：分离控制、触摸手势、隐藏准星。
您可以在预设列表中排序、复制预设，或进行重命名、修改设置等。

图层系统

图层系统来自 #123 以及相关的各种 issue，其用途是在不同的情况下显示不同的控件，例如飞行、划船时。

每个图层都可以配置显示条件，如果多个图层同时满足条件会叠加图层。
TouchController 的控件必须在图层中创建。

图层编辑

是一个子页面，可以编辑图层名称和图层条件。可以在右侧的标签页中将图层条件添加到图层中，目前有三个标签页：

预置条件：TouchController v0.2.1-beta11 及以前仅可用这种预置条件，包含游泳中、飞行中、潜水中、允许飞行等等。
手持物品：包含类似物品列表的默认物品表及原版物品栏，点击一个物品可以添加手持此物品的条件。
乘坐实体：包含一个实体列表，几乎包含游戏中的所有实体类型。
选择实体：同上
自定义条件：参见自定义图层条件。

条件状态

每个条件拥有以下几种状态：

从不：条件满足时不显示图层
要求：条件满足时显示图层
必须：所有“必要”条件满足时显示图层

自定义图层条件

自定义图层条件是为了通过自定义控件控制图层而设计的，自定义图层条件与预设绑定，不同预设中的自定义图层条件不会互相干扰。

可以在图层编辑页面编辑自定义图层条件，如添加、重命名和删除。添加的自定义图层条件将显示在同预设所有图层的自定义条件页面中。

内置控件

TouchController 的内置控件主要是基于自定义控件实现的，但也有一些控件无法通过标准自定义控件实现，它们有一些不同于自定义控件的设置。通过自定义控件实现的内置控件在此不再赘述（您可以直接查看其属性以了解其特性），我们主要介绍无法通过标准自定义控件实现的内置控件：

方向键

方向键除了可以调整大小、调整图集外，还可以有以下设置：

显示左后和右后按键：是否显示左后和右后的斜向按键贴图
边距：方向键各个按钮之间的间距
中心按钮（游戏内名称：附加按钮）：中心按钮可以独立调整大小、激活贴图，并且包含无、普通、滑动无锁定、滑动锁定四种类型：
- 无：不显示中心按钮
- 普通：操作与普通控件拥有相同的设置
- 滑动无锁定：手指滑过中心按钮后触发，操作与普通控件拥有相同的设置
- 滑动锁定：手指滑过中心按钮后触发一次，操作只能设为绑定键位

虚拟摇杆

虚拟摇杆除了可以修改图集外，还可以分别调整背景和手柄的大小，同时拥有两个选项：

触发疾跑：摇杆推到 110% 后触发疾跑
激活时提高不透明度：手指移动摇杆时，摇杆提高不透明度

划船按钮

划船按钮较为特殊，就像坦克一样，按住左边的按钮可以右转，按住右边的按钮可以左转，按住两个按钮可以同时前进。

划船按钮除了可以调整大小、调整图集外，还可以设置当前按钮为左侧按钮或右侧按钮。

自定义控件

TouchController 几乎所有的控件都是基于同一个自定义架构实现的，这也表明了TouchController 的自定义控件拥有的极高自由度。在自定义控件布局中的控件标签页中，有一个“内置控件”和一个“模板控件”。您可以在“内置控件”中添加控件，在此基础上修改后保存到“模板控件”中，然后在其他页面中使用，下文将详细的描述自定义控件的方法。

外观

您一共可以为一个控件配置两种外观，分别是正常状态下和激活状态下，您也可以选择激活后不改变贴图或贴图变灰。特别地，文本和文本颜色的配置不能随着控件的激活状态而改变。除此之外，以下几种属性都可以随着控件的激活状态而改变：

填充：在这个模式下，您可以使用颜色填充控件，也可以为其设置边框：边框宽度和边框颜色。这个模式下的控件大小会随着文本长度而改变，您可以为文本设置边距：上、下、左、右。
固定贴图：在这个模式下，您可以将控件设置为 TouchController 所拥有的任何控件贴图（~~甚至包括摇杆手柄和摇杆背景~~）。在此模式下，您还可以调整控件缩放，最高为400%。
自适应贴图：在这个模式下，您可以选择一些控件的背景作为自定义控件的背景。这个模式下的控件大小会随着文本长度而改变，您可以为文本设置边距：上、下、左、右。

动作

大部分操作都可以有四种选择：无、键位、玩家操作、游戏操作。

无：不做任何操作
键位：执行 Minecraft “按键绑定”中某个条目的操作，但并非发送键值。在此模式下可以选择触发后锁定，锁定后相当于持续激活这个键位。锁定类型有三种：开始、停止、和反转。顾名思义，“开始”就是触发操作后开始锁定这个控件；“停止”就是触发操作后停止锁定这个控件；“反转”就是触发操作后反转锁定状态。当然，您也可以选择不锁定，此时可以使用一个选项“保持一个客户端刻”，如果遇到某些时候操作按键无效，请启用这个选项。
玩家操作：触发玩家的某个操作：如停止飞行、开始疾跑、停止疾跑
游戏操作：触发某个游戏操作：如打开游戏菜单、打开聊天界面等
图层条件：切换、启用、禁用某自定义图层条件

触发

按下：手指按下控件的瞬间触发，这个操作可以有上述四种选择。
按住：手指按下控件后持续触发，这个操作只能绑定键位（具体见上）。
松开：手指按下控件后松开的瞬间触发，这个操作可以有上述四种选择。
双击：手指双击控件后的瞬间触发，并且可以设置两次点击控件的判定间隔，这个操作可以有上述四种选择。

锚点机制

锚点机制旨在适配不同大小的屏幕，使得控件布局在任何设备上都可用。

锚点共有 9 种，分别为屏幕四角、屏幕四边的中心、屏幕中心。
无论画面边框如何变化，控件相对其锚点的位置始终不变。

静默转头

这个机制起源于 #148 和 #153，其主要内容是 TouchController 无法在正确的位置进行某些交互，其典型例子便是使用水桶放水。

众所周知，只要不开启分离控制，那么您点击屏幕的位置便是实际交互的位置。但是在手持水桶点击屏幕时，水却直接放置在了准星所对准的位置，就像基岩版中的末影珍珠一样。这是因为 Minecraft 的服务端（单人游戏会使用内置服务端）没有使用 TouchController 提供的目标位置。

为什么不使用呢？

我们先讲一下 Minecraft 寻找目标的机制，Minecraft 通常是在客户端处理这件事情的，所以 TouchController 可以直接通过修改客户端来给服务端提供正确的目标位置。但是这个默认机制会忽略掉流体，因此这种机制下流体永远不能成为目标。那我们如何装水、如何放船呢？

为此，Minecraft 为某些物品启用了一个特殊的机制，这个机制与默认机制不同，能正确地判定目标。但是这个机制会同时在客户端和服务端运行，此时服务端不再使用来自客户端的目标，而是根据玩家的实际朝向来确认目标。

为了让水桶等物品的交互方向正确，TouchController 加入了静默转头的机制（具体机制见下一节），并且可以在“需要修正使用方向的物品”中配置。通过适当配置，您甚至可以完成一些基岩版中做不到的操作。在基岩版中，使用末影珍珠会直接向准星方向扔出，即使未启用分离控制。但如果您在 TouchController 中将末影珍珠加入静默转头物品表，您就可以实现“指哪打哪”的投掷效果。

机制

未开启分离控制时，手持“需要修正使用方向的物品”中的物品，点击屏幕进行交互后 TouchController 会进行转头，使准星对准点击的方向 -> 交互 -> 然后再恢复原位。这一切都在一帧之内完成，这样您的客户端或服务器内其他玩家的客户端都不会渲染您的转头动作，故称为“静默转头”。

文本输入适配

TouchController 能够在您选中输入框（注：目前仅限于 TouchController 的 GUI，将在未来支持原版 GUI）时自动弹出触摸键盘。还能让弹出键盘时输入框移动到键盘顶部，在输入时为输入法提供文本框中的内容，就像在其他应用程序中那样。

Windows 系统

Tip

Windows 系统中仅实现了自动弹出键盘。

在 Windows 系统中，弹出键盘存在诸多条件。首先，Windows 需要能识别到触摸屏。此外，还需要在设置中启用相关功能。以Windows 11 为例，您需要打开设置，找到时间和语言 -> 输入，展开触摸键盘选项，将显示触摸键盘设为未连接键盘时或始终。此时，找到一个输入框，选中它，触摸键盘应该能自动弹出。在游戏内，触摸键盘也会以同样的方式弹出。