三笠传送指令 · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

Mikasa-tp-mod

Mikasa-tp-mod 是由 Mikasa 开发的 Fabric 服务端传送工具。

它添加了玩家传送、带短暂原地不动预热时间的 TPA 请求，以及多个具名家园。权限由可配置的角色控制。存储开箱即用，支持 JSON，并可选用 PostgreSQL 或 MySQL。

可用命令

/tphelp
/tp <player>
/tpa <player>
/tpaccept
/tpdeny
/tpacancel
/home list
/home set <name>
/home del <name>
/home <name>

理念

完全掌控你的数据与角色。

Mikasa-tp-mod 是为那些想要掌控一切的人打造的——而不是“又一个 TP 模组”。没有魔法，也没有隐藏的决定：你的数据归你，你的角色归你，一切都恰好存在于你放置它们的地方。

你的数据，你做主

PostgreSQL 或 MySQL——适用于数据必须可靠的高负载服务器。
JSON——如果不需要数据库或尚未准备好。
切换只需改动一处配置。无需外部插件，没有依赖。

由你定义角色

权限通过角色授予：player、moderator、admin——或者像 vip 这样的自定义角色。每个角色能做什么完全由你决定。没有角色——就没有访问权限。透明且可预测。

数据库自动完成初始化

如果你有 PostgreSQL 或 MySQL 但不想处理架构——模组会替你完成。首次连接时会自动创建所需的最少表：

roles——角色
commands——命令键
role_permissions——角色权限
players——玩家与角色的绑定
settings——诸如 max_homes 的设置
homes——玩家家园

无需编写 SQL，无需手动创建表。只需提供主机、数据库、用户名和密码——剩下的交给模组处理。

将配置从 JSON 迁移到数据库

在 config.json 中有一个键 sync_to_database（默认值：false）。

将其设为 true——在下次服务器启动时，整个 JSON 配置将完全迁移到数据库中：

角色及其权限，
命令列表，
设置（例如 max_homes）。

迁移在单个事务中运行：全有或全无。成功后，模组会将该键重置回 false——因此迁移只运行一次，你无需再操心。

这意味着你可以从 JSON 起步，只需一个开关就能切换到数据库——无需手动 SQL，没有数据丢失。

编辑配置是安全的

只要角色本身仍保留在 config.json 中，玩家到角色的绑定就会保留。

编辑配置时没有什么可担心的：只要某个角色仍存在于文件中，分配给它每一位玩家在同步后都会继续保持。如果你删除了一个角色，其玩家不会丢失——他们会自动移至 player。家园则完全不会被触碰。

随意编辑你的配置：同步逻辑的设计确保不会丢失任何东西。

你的数据不会丢失

家园在角色同步期间绝不会被触碰。
处于已删除角色上的玩家会被移至 player，而不会丢失。
迁移在单个事务中运行：全有或全无。

为什么这很重要

以前，要获得一个轻量级传送模组，就意味着要切换到 Paper 或 Purpur——仅仅为了 /tp、/tpa 和 /home。现在不再需要这样做了。

Mikasa-tp-mod 在纯 Fabric 上解决了这个问题。

命令总览

命令	用途
`/tphelp`	显示完整命令列表（以私信形式发送给玩家）
`/tp <player>`	将自己传送到另一位在线玩家处（受角色限制）
`/tpa <player>`	向另一位玩家发送传送请求
`/tpaccept`	接受收到的 TPA 请求
`/tpdeny`	拒绝收到的 TPA 请求
`/tpacancel`	取消你发出的 TPA 请求或预热
`/home set <name>`	在你当前的位置保存一个具名家园
`/home <name>`	传送到你保存的某个家园
`/home del <name>`	删除一个已保存的家园
`/home list`	列出你所有的家园

TPA 包含一个短暂的原地不动预热时间，并带有屏幕倒计时。预热期间移动会取消传送。

所有 /home 子命令共享同一个权限键 home。

依赖项

Minecraft 26.3——必需
重要： Fabric Loader 0.19.5 或更高版本——不支持更早的加载器版本（例如 0.19.3）
Fabric API（适用于 Minecraft 26.3）——必需
Java 25+——必需

可选（运行模组并非必需）：

PostgreSQL 或 MySQL 服务器——仅当你共享的 configdatabase.json 中启用数据库存储时需要

数据库 JDBC 驱动已捆绑在模组 jar 中。没有数据库时，模组会自动使用 JSON 存储。

配置（首次启动时创建）

在首次服务器启动时，模组会自动创建其配置文件夹和文件：

config/Mikasa-tp-mod/config.json——角色、命令权限、家园（JSON 存储）、诸如 max_homes 的设置，以及 sync_to_database
config/Mikasa-tp-mod/README.md——写在配置旁的设置说明
config/Mikasa-mods-general/database/configdatabase.json——Mikasa 模组的可选共享数据库连接设置（默认禁用）

你可以编辑这些文件来配置权限、家园上限以及可选的数据库同步。首次运行前无需手动创建文件。

安装

在你的服务器上安装适用于 Minecraft 26.3 的 Fabric Loader（重要： 使用 0.19.5+）。
将此模组和 Fabric API 放入服务器的 mods 文件夹。
启动一次服务器，以便生成配置文件。
如有需要，编辑配置，然后在游戏内使用 /tphelp。

注意： 这是一个服务端模组。玩家无需在客户端安装它。

Jar 文件名：Mikasa-tp-mod-fabric-26.3-2.0.jar

许可证

MIT——作者：Mikasa

存储模式

模式	何时使用	角色 / 设置 / 家园
JSON	数据库禁用、配置错误或不可达	`config.json`
数据库	共享的 `configdatabase.json` 可用且连接成功	SQL 表

启动时若连接成功则优先使用数据库。如果运行时数据库查询失败，许多路径会回退到 JSON。

启动日志示例：

launch config: database (postgres|mysql)
launch config: file

`config/Mikasa-mods-general/database/configdatabase.json`

在 Mikasa 模组之间共享。默认创建为空 / 禁用。示例：

{
  "type": "postgres",
  "enabled": true,
  "host": "127.0.0.1",
  "port": 5432,
  "database": "minecraft",
  "username": "minecraft",
  "password": "secret"
}

MySQL / MariaDB：

{
  "type": "mysql",
  "enabled": true,
  "host": "127.0.0.1",
  "port": 3306,
  "database": "minecraft",
  "username": "minecraft",
  "password": "secret"
}

字段	说明
`type`	`postgres` / `postgresql` / `pg` → PostgreSQL；`mysql` / `mariadb` / `sql` → MySQL
`enabled`	必须为 `true` 才能连接
`host`、`database`、`username`	启用时必需
`port`	默认值：Postgres `5432`，MySQL `3306`
`password`	连接密码

JDBC 驱动（PostgreSQL、MySQL）和 HikariCP 已捆绑在模组 jar 中。你不需要为数据库驱动添加额外的 jar。

连接成功后，模组会运行 CREATE TABLE IF NOT EXISTS ... 并写入默认数据（player 角色，max_homes = 5）。

数据库结构

表会自动创建。逻辑架构：

`roles`

列	类型（概念）	描述
`name`	text / varchar PK	角色 id，例如 `player`、`moderator`、`admin`

初始写入：player。

`commands`

列	类型	描述
`name`	text / varchar PK	权限 / 命令键，例如 `tp`、`home`

`role_permissions`

列	类型	描述
`role_name`	FK → `roles`	角色
`command_name`	FK → `commands`	命令键
`allowed`	boolean	`true` = 允许，`false` = 拒绝
PK	(`role_name`, `command_name`)

如果某个角色+命令没有行，模组会将其视为拒绝。

`players`

列	类型	描述
`uuid`	UUID / CHAR(36) PK	玩家 UUID
`name`	text / varchar	最后已知名称（可选元数据）
`role_name`	FK → `roles`，默认 `player`	分配的角色

重要： 本模组会读取玩家角色以进行权限检查。它不会在正常游戏过程中创建或更新玩家行（加入时不自动注册）。你需要自己分配角色（SQL、管理工具或 JSON——见下文）。

`settings`

列	类型	描述
`key`	text / varchar PK	设置名称
`value`	text / varchar	字符串值

模组使用的已知设置：

键	默认值	含义
`max_homes`	`5`	`/home set` 每位玩家的家园上限（仅限新家园）

`homes`

列	类型	描述
`player_uuid`	UUID / CHAR(36)	所有者
`home_name`	text / varchar	家园 id
`world`	text / varchar	维度 id（例如 `minecraft:overworld`）
`x`、`y`、`z`	double	位置
`yaw`、`pitch`	float	朝向
PK	(`player_uuid`, `home_name`)

家园在 /home set 时进行 upsert，在 /home del 时删除。

PostgreSQL 参考 DDL

CREATE TABLE IF NOT EXISTS roles (
    name TEXT PRIMARY KEY
);

CREATE TABLE IF NOT EXISTS commands (
    name TEXT PRIMARY KEY
);

CREATE TABLE IF NOT EXISTS role_permissions (
    role_name TEXT NOT NULL REFERENCES roles(name) ON DELETE CASCADE,
    command_name TEXT NOT NULL REFERENCES commands(name) ON DELETE CASCADE,
    allowed BOOLEAN NOT NULL DEFAULT FALSE,
    PRIMARY KEY (role_name, command_name)
);

CREATE TABLE IF NOT EXISTS players (
    uuid UUID PRIMARY KEY,
    name TEXT,
    role_name TEXT NOT NULL DEFAULT 'player' REFERENCES roles(name)
);

CREATE TABLE IF NOT EXISTS settings (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL
);

CREATE TABLE IF NOT EXISTS homes (
    player_uuid UUID NOT NULL,
    home_name TEXT NOT NULL,
    world TEXT NOT NULL,
    x DOUBLE PRECISION NOT NULL,
    y DOUBLE PRECISION NOT NULL,
    z DOUBLE PRECISION NOT NULL,
    yaw REAL NOT NULL,
    pitch REAL NOT NULL,
    PRIMARY KEY (player_uuid, home_name)
);

INSERT INTO roles (name) VALUES ('player') ON CONFLICT DO NOTHING;
INSERT INTO settings (key, value) VALUES ('max_homes', '5') ON CONFLICT DO NOTHING;

MySQL 使用兼容的类型（VARCHAR、CHAR(36)、DOUBLE、FLOAT 等），表 / 列名相同。

`config.json` 结构

{
  "sync_to_database": false,
  "settings": {
    "max_homes": 5
  },
  "roles": {
    "player": {
      "commands": {
        "tphelp": true,
        "tp": false,
        "home": true,
        "tpa": true,
        "tpaccept": true,
        "tpdeny": true,
        "tpacancel": true
      }
    },
    "moderator": {
      "commands": {
        "tphelp": true,
        "tp": true,
        "home": true,
        "tpa": true,
        "tpaccept": true,
        "tpdeny": true,
        "tpacancel": true
      }
    },
    "admin": {
      "commands": {
        "tphelp": true,
        "tp": true,
        "home": true,
        "tpa": true,
        "tpaccept": true,
        "tpdeny": true,
        "tpacancel": true
      }
    }
  },
  "players": {},
  "homes": {}
}

默认权限矩阵

命令	`player`	`moderator`	`admin`
`tphelp`	是	是	是
`tp`	否	是	是
`home`（`set` / `<name>` / `del` / `list`）	是	是	是
`tpa` / `tpaccept` / `tpdeny` / `tpacancel`	是	是	是

Players 块（JSON 模式）

"players": {
  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": {
    "name": "Steve",
    "role": "moderator"
  }
}

玩家条目缺失 → 视为角色 player。

Homes 块（JSON 模式）

"homes": {
  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": {
    "spawn": {
      "world": "minecraft:overworld",
      "x": 0.0,
      "y": 64.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0
    }
  }
}

角色如何工作

解析顺序

查找玩家的角色（若已连接数据库则查 players 表，否则查 config.json → players）。
若未知 / 缺失 → 角色 player。
检查该角色 + 命令键的权限。
权限条目缺失 → 拒绝。

只有玩家可以使用这些命令（控制台会被权限门拒绝）。

创建 / 添加角色（JSON）

打开 config/Mikasa-tp-mod/config.json。
在 roles 下添加一个新对象，例如：

"vip": {
  "commands": {
    "tphelp": true,
    "tp": true,
    "home": true,
    "tpa": true,
    "tpaccept": true,
    "tpdeny": true,
    "tpacancel": true
  }
}

在 players（JSON）或 players SQL 表（数据库模式）中将某位玩家分配到该角色。
根据文件重新加载的时机，JSON 编辑并不总是需要重启；最稳妥的做法是在角色编辑后重启服务器。
如果你使用数据库并希望 SQL 表与此文件匹配，请使用 sync_to_database（下一节）。

创建 / 添加角色（SQL，手动）

INSERT INTO roles (name) VALUES ('vip')
  ON CONFLICT DO NOTHING;

INSERT INTO commands (name) VALUES
  ('tphelp'), ('tp'), ('home'),
  ('tpa'), ('tpaccept'), ('tpdeny'), ('tpacancel')
  ON CONFLICT DO NOTHING;

INSERT INTO role_permissions (role_name, command_name, allowed) VALUES
  ('vip', 'tphelp', TRUE),
  ('vip', 'tp', TRUE),
  ('vip', 'home', TRUE),
  ('vip', 'tpa', TRUE),
  ('vip', 'tpaccept', TRUE),
  ('vip', 'tpdeny', TRUE),
  ('vip', 'tpacancel', TRUE)
ON CONFLICT (role_name, command_name) DO UPDATE SET allowed = EXCLUDED.allowed;

为玩家分配角色

JSON：

"players": {
  "uuid-here": { "name": "Steve", "role": "vip" }
}

SQL：

INSERT INTO players (uuid, name, role_name)
VALUES ('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'Steve', 'vip')
ON CONFLICT (uuid) DO UPDATE
SET name = EXCLUDED.name, role_name = EXCLUDED.role_name;

请记住：模组不会在玩家加入时自动创建 players 行。

`sync_to_database`——覆盖 / 重写如何工作

这是内置的一次性同步。正常使用无需外部 Python 脚本。

何时运行

在服务器启动时，数据库连接成功后：

如果 sync_to_database 为 false → 不执行任何操作。
如果为 true 但数据库未连接 → 同步会跳过；该标志保持为 true（下次启动时重试）。
如果为 true 且数据库已连接 → 同步在事务内运行，然后模组将 sync_to_database 设回 false 并保存 config.json。

如何使用

按你希望数据库呈现的样子编辑 config.json 中的 roles 和 settings。
确保共享的 config/Mikasa-mods-general/database/configdatabase.json 已启用且正确。
设置 "sync_to_database": true。
重启服务器。
检查日志确认同步成功；标志应恢复为 false。

会写入 / 覆盖什么

从 config.json 写入数据库：

数据	操作
`roles` 下列出的角色	Upsert 到 `roles`
角色 `player`	始终确保存在
在角色映射中找到的命令键	Upsert 到 `commands`
每个角色 × 命令的 `allowed` 标志	Upsert 到 `role_permissions`
`settings`（例如 `max_homes`）	Upsert 到 `settings`
配置中不存在的角色 / 命令 / 权限	从数据库中清除（删除）

什么会被保留

数据	行为
`homes` 表	同步绝不触碰
`players` 分配	同步期间不会从 JSON 的 `players` 重写
处于已删除角色上的玩家	在该角色被移除前移至角色 `player`
角色 `player`	永不会被清除删除

同步顺序（单个事务）

确保 player 角色
Upsert 期望的角色
Upsert 期望的命令
Upsert 权限行
删除过时的权限
删除过时的命令
删除过时的角色（在将受影响玩家移至 player 之后）
Upsert 设置
提交
设置 sync_to_database = false 并保存 JSON

失败时：回滚，标志保持 true，记录错误。

警告

同步会替换数据库中的角色 / 权限 / 设置图景，改为 config.json 中的内容。你从 JSON 中移除的旧角色会从 SQL 中删除（处于这些角色上的玩家会被降级为 player）。家园保持不变。

可选的外部同步（`shared-db`）

有一个单独的文件夹 mods/shared-db，内含 Postgres 辅助工具（schema.sql、roles.json、sync_roles.py）。行为类似（upsert + 清除角色 / 权限 / 设置；不擦除家园）。

对本模组，推荐使用 config.json 中的 sync_to_database。Python 工具是可选的 / 共享工具，并非运行 Mikasa-tp-mod 所必需。

家园详情

上限：settings.max_homes（JSON 或数据库）。
在创建新家园名称时强制执行；更新已有名称不会消耗另一个槽位。
世界以维度 id 字符串存储。
数据库连接时，家园位于 homes 表中；否则位于 config.json → homes 中。

依赖项（摘要）

依赖项	是否必需？
Minecraft 26.3	是
Fabric Loader 0.19.5+（重要）	是
Fabric API	是
Java 25+	是
PostgreSQL / MySQL 服务器	否（可选存储）

源码

https://github.com/Mikasa-not-available/Mikasa-tp-mod