ViScriptTeam

ViScriptTeam

一个轻量级的派系关系模组，适用于RPG地图、PVE地图以及以故事驱动的Minecraft服务器。它提供派系数据、实体派系分配、每个玩家的声望、派系间敌对关系、友军伤害控制、派系感知的怪物目标选择以及颜色编码的名称标签。

该模组并非原版队伍系统的替代品。它被设计为一个专门的派系层，供地图制作者用来模拟怪物、NPC、势力与玩家之间的关系。

核心概念

派系

派系是实体分配和玩家声望的基本单位。派系ID会自动规范化为小写字母（例如 Guards 变为 guards）。

每个派系定义以下内容：

• 默认声望值 — 每个玩家对该派系的初始声望。
• 中立阈值 — 低于此值的声望被视为敌对；达到或高于此值时，玩家至少为中立。
• 友好阈值 — 达到或高于此值的声望被视为友好。
• 友军伤害开关 — 同派系的实体或友好玩家之间是否可能互相造成伤害。
• 攻击敌对派系开关 — 该派系的实体是否会主动 targeting 敌对派系的成员。
• 敌对派系列表 — 该派系视为敌对的其他派系ID集合。

默认配置：

范围	态度
< 50	敌对
50 – 99	中立
>= 100	友好

实体派系

任何非玩家实体都可以被分配到一个派系。这适用于怪物、NPC、守卫、刷怪笼生成的生物以及地图机制实体。

实体派系分配通过UUID存储，因此只要实体仍存在于世界中，其分配关系就会在实体重载后持续存在。

玩家不使用实体派系系统来表达身份。相反，玩家与派系的关系通过每个玩家的声望来表达，这为未来的队伍设计保留了灵活性。

玩家声望

每个玩家都独立维护对每个派系的声望值。该数值决定了该派系对该玩家的态度：

• 敌对 — 派系视玩家为敌人。该派系的实体将主动 targeting 该玩家并造成伤害。
• 中立 — 派系既不攻击玩家也不保护玩家。
• 友好 — 派系视玩家为盟友。友军伤害规则适用，除非派系允许友军伤害，否则该玩家受到同派系实体的伤害保护。

声望可以设置为绝对值，也可以通过增减量进行调整，使其适用于任务奖励、击杀惩罚、剧情触发和渐进式声望系统。

队伍

队伍是一个独立于派系的分组系统。它们专为任务、地下城实例、剧情事件以及需要知道“当前哪些玩家在一起组队”的脚本驱动逻辑而设计。

每个队伍包含：

• 队伍ID — 一个唯一且规范化的标识符。
• 队长 — 领导队伍的玩家。如果队长离开，下一位成员会自动晋升为队长。
• 成员列表 — 当前队伍中的所有玩家。
• 友军伤害开关 — 队伍成员之间是否可以互相造成伤害。

一个玩家同一时间只能属于一个队伍。加入新队伍会自动离开之前的队伍。没有剩余成员的队伍会被自动移除。

派系间敌对关系

派系之间的敌对关系是单向的。如果你希望派系A和派系B相互敌对，你必须同时添加两个方向：

• A -> B 不会自动创建 B -> A。

这种设计允许不对称关系的存在，例如一个派系敌视另一个派系，但对方并不对其抱有敌意。

行为细节

名称标签颜色

客户端会根据观察玩家对实体所属派系的有效态度，为实体名称标签渲染颜色提示：

态度	颜色
友好	绿色
中立	黄色
敌对	红色

该模组不会强制显示名称标签。可见性仍由原版机制或其他模组控制（例如 CustomNameVisible、实体名称显示规则、地图制作者设置的NBT数据）。

名称标签数据会在登录、重生、切换维度以及派系/声望数据被修改时同步到客户端。如果玩家在队伍中，有效态度将根据队伍的站立策略计算。

伤害规则

该模组会拦截伤害事件以执行派系和队伍规则，作为一种安全网，即使自定义AI或其他机制绕过了正常的目标选择：

• 同一队伍 — 队伍成员之间不能互相伤害，除非队伍启用了友军伤害。
• 同一派系 — 同一派系内的实体不能互相伤害，除非该派系允许友军伤害。
• 玩家 vs. 友好派系 — 当玩家对某派系持友好态度时，除非该派系允许友军伤害，否则玩家与该派系的实体均不能对对方造成伤害。
• 中立 — 中立关系不提供伤害保护，但实体也不会主动 targeting 中立玩家。
• 敌对 — 始终允许造成伤害。

怪物目标选择

该模组会在服务端向所有 Mob 实体注入一个低优先级的派系目标选择目标：

• 未分配派系的实体完全不受影响 — 无额外扫描开销。
• 已分配派系的实体将：
  • 主动 targeting 对其派系持敌对态度的玩家。
  • 主动 targeting 属于敌对派系的实体（如果该派系的“攻击敌对派系”开关已启用）。
  • 绝不 targeting 同一派系的实体。
• 目标选择目标以低优先级运行，使其兼容原版AI和大多数使用标准目标系统的模组实体。
• 每tick进行一次合理性检查，清除无效目标，并在怪物 targeting 受保护实体时停止导航。

对于完全自定义的AI实现，模组提供了可直接调用的 FactionApi 方法。

队伍有效立场

队伍不存储自己的派系声望。相反，在需要确定派系态度时，会根据成员声望动态计算有效立场。

默认策略为 min — 即所有队伍成员中最低的声望。这可以防止敌对玩家加入友好队伍以绕过守卫敌意、怪物AI、地下城访问或派系权限。

内置策略：

策略	描述	推荐用途
min	最低成员声望（默认）	守卫敌意、敌人侦测、地下城访问控制
average	成员平均声望，向下取整	定居点显示、软性评估
leader	仅使用队长的声望	剧情触发器、任务入口点
max	最高成员声望	特殊脚本，其中“队伍中任何人了解此派系”即可

所有原版/模组的目标选择、伤害拦截和名称标签颜色均使用默认的 min 策略。个别玩家的声望始终独立存储 — 队伍仅仅是评估派系关系的运行时视角。

数据持久化

所有派系数据、实体分配、玩家声望和队伍成员资格均存储在世界保存数据中（附加于主世界）。这意味着：

• 数据在服务器重启后持续存在。
• 删除派系会自动清理所有关联的实体分配、玩家声望以及其他派系中的敌对派系引用。
• 队伍成员变更会立即保存。