ViScriptTeam
一款用于 RPG 地图、PVE 地图和剧情驱动 Minecraft 服务器的轻量级阵营关系模组。它提供阵营数据、实体阵营分配、玩家个人声望、阵营间敌对关系、友军伤害控制、阵营感知型生物目标锁定以及彩色名称标签等功能。
本模组并非原版团队系统(team system)的替代品。它是专为需要模拟怪物、NPC、势力与玩家之间关系的地图制作者设计的专用阵营层。
核心概念
阵营 (Factions)
阵营 (Faction) 是实体分配和玩家声望的基本单位。阵营 ID 会自动规范化为小写(例如 Guards 变为 guards)。
每个阵营定义如下:
- 默认声望点数 — 每位玩家对该阵营的初始声望值。
- 中立阈值 — 低于此值的声望被视为敌对 (Hostile);达到或高于此值时,玩家至少处于中立 (Neutral) 状态。
- 友好阈值 — 达到或高于此值的声望被视为友好 (Friendly)。
- 友军伤害开关 — 同阵营实体或友好玩家是否可以互相造成伤害。
- 攻击敌对阵营开关 — 该阵营内的实体是否会主动攻击敌对阵营的成员。
- 敌对阵营列表 — 该阵营视为敌对的阵营 ID 集合。
默认配置:
| 范围 |
态度 |
< 50 |
敌对 |
50 – 99 |
中立 |
>= 100 |
友好 |
实体阵营 (Entity Factions)
任何非玩家实体都可以被分配到某个阵营。这适用于生物、NPC、守卫、刷怪笼生成的生物以及由地图机制控制的实体。
实体阵营分配通过 UUID 存储,因此只要实体保留在世界中,即使实体重新加载,其阵营归属也会持久保存。
玩家不使用实体阵营系统来表达身份。相反,玩家与阵营的关系通过“玩家个人声望”来体现,这使得系统在未来的组队设计方面保持灵活。
玩家声望 (Player Reputation)
每位玩家针对每个阵营都维护着独立的声望分数。该分数决定了该阵营对玩家的态度:
- 敌对 (Hostile) — 该阵营将玩家视为敌人。该阵营内的实体将主动锁定玩家并造成伤害。
- 中立 (Neutral) — 该阵营既不攻击也不保护玩家。
- 友好 (Friendly) — 该阵营将玩家视为盟友。适用友军伤害规则,除非该阵营允许友军伤害,否则玩家将受到同阵营实体的保护而不受伤害。
声望可以设置为绝对值或通过增量进行调整,使其适用于任务奖励、击杀惩罚、剧情触发器以及渐进式声望系统。
队伍 (Parties)
队伍是一个独立于阵营之外的分组系统。它旨在服务于任务、副本实例、剧情事件以及需要知晓“哪些玩家当前组队在一起”的脚本驱动逻辑。
每个队伍包含:
- 队伍 ID — 唯一的、规范化后的标识符。
- 队长 (Leader) — 领导队伍的玩家。如果队长离开,下一位成员将自动晋升为队长。
- 成员列表 — 当前所有在队伍中的玩家。
- 友军伤害开关 — 队伍成员之间是否可以互相造成伤害。
玩家同一时间只能属于一个队伍。加入新队伍会自动退出之前的队伍。没有剩余成员的空队伍会被自动移除。
阵营间敌对关系 (Inter-Faction Hostility)
阵营间的敌对关系是单向的。如果你希望阵营 A 和阵营 B 相互敌对,你必须添加两个方向的设置:
这种设计允许非对称关系,例如一个阵营对另一个阵营持有敌意,但对方并不回敬。
行为细节
名称标签颜色 (Name Tag Colors)
客户端会根据观看者玩家对实体所属阵营的有效态度,以颜色提示渲染实体的名称标签:
本模组不会强制显示名称标签。可见性仍由原版机制或其他模组(如 CustomNameVisible、实体名称显示规则、地图制作者设置的 NBT 数据)控制。
名称标签数据会在登录、重生、维度切换以及阵营/声望数据修改时同步到客户端。如果玩家身处队伍中,有效态度将根据队伍的立场策略进行计算。
伤害规则 (Damage Rules)
模组会拦截伤害事件,作为安全网以强制执行阵营和队伍规则,即使自定义 AI 或其他机制绕过了正常的目标选择:
- 同队伍 — 除非队伍启用了友军伤害,否则队伍成员无法互相伤害。
- 同阵营 — 除非阵营允许友军伤害,否则同阵营实体无法互相伤害。
- 玩家 vs. 友好阵营 — 当玩家对某阵营持友好态度时,除非该阵营允许友军伤害,否则玩家与该阵营的实体均无法互相伤害。
- 中立 — 中立关系不提供伤害保护,但实体也不会主动锁定中立玩家。
- 敌对 — 始终允许造成伤害。
生物目标锁定 (Mob Targeting)
模组在服务端向所有 Mob 实体注入一个低优先级的阵营目标锁定目标:
- 未分配阵营的实体完全不受影响 — 不会产生额外的扫描开销。
- 已分配阵营的实体将:
- 主动攻击对其阵营持敌对态度的玩家。
- 主动攻击属于敌对阵营的实体(如果启用了该阵营的“攻击敌对阵营”开关)。
- 永远不会攻击同一阵营内的实体。
- 目标选择逻辑以低优先级运行,因此与原版 AI 以及使用标准目标系统的绝大多数模组实体兼容。
- 每刻执行一次健全性检查,清除无效目标;如果 mobs 意外锁定了受保护实体,则停止导航。
对于完全自定义的 AI 实现,模组提供了可直接调用的 FactionApi 方法。
小队有效声望
小队不存储自身的阵营声望。相反,当需要确定阵营态度时,会根据成员的声望动态计算有效声望。
默认策略为 min — 即所有小队成员中最低的声望。这可以防止敌对玩家加入友好小队,从而绕过守卫敌意、Mob AI、地牢访问或阵营权限限制。
内置策略:
| 策略 |
描述 |
推荐用途 |
min |
最低成员声望(默认) |
守卫敌意、敌人检测、地牢访问控制 |
average |
成员声望平均值,向下取整 |
定居点显示、软性评估 |
leader |
仅领袖声望 |
剧情触发、任务入口点 |
max |
最高成员声望 |
“小队中任何人认识此阵营”即可的特殊脚本 |
所有原版/模组的锁定、伤害拦截和名称标签颜色均使用默认的 min 策略。单个玩家的声望始终独立存储 — 小队仅作为运行时评估阵营关系的视角。
数据持久化
所有阵营数据、实体分配、玩家声望和小队成员信息均存储在世界的保存数据中(附加于主世界)。这意味着:
- 数据在服务器重启后保留。
- 删除某个阵营会自动清理所有相关的实体分配、玩家声望以及其他阵营中的敌对阵营引用。
- 小队成员变更会立即保存。
ViScriptTeam
A lightweight faction relationship mod for RPG maps, PVE maps, and story-driven Minecraft servers. It provides faction data, entity faction assignment, per-player reputation, inter-faction hostility, friendly-fire control, faction-aware mob targeting, and color-coded name tags.
This mod is not a replacement for the vanilla team system. It is designed as a dedicated faction layer for map makers who need to model relationships between monsters, NPCs, forces, and players.
Core Concepts
Factions
A Faction is the fundamental unit for entity assignment and player reputation. Faction IDs are automatically normalized to lowercase (e.g. Guards becomes guards).
Each faction defines:
- Default reputation points — the starting reputation every player has toward this faction.
- Neutral threshold — reputation below this value is considered Hostile; at or above this value the player is at least Neutral.
- Friendly threshold — reputation at or above this value is considered Friendly.
- Friendly fire toggle — whether same-faction entities or friendly players can damage each other.
- Attack enemy factions toggle — whether entities in this faction will actively target members of enemy factions.
- Enemy faction list — a set of faction IDs this faction considers hostile.
Default configuration:
| Range |
Attitude |
< 50 |
Hostile |
50 – 99 |
Neutral |
>= 100 |
Friendly |
Entity Factions
Any non-player entity can be assigned to a faction. This is intended for mobs, NPCs, guards, spawner-spawned creatures, and map-mechanic entities.
Entity faction assignment is stored by UUID, so it persists across entity reloads as long as the entity remains in the world.
Players do not use the entity faction system to express identity. Instead, player-faction relationships are expressed through per-player reputation, keeping the system flexible for future party design.
Player Reputation
Each player maintains an independent reputation score for every faction. The score determines the faction's attitude toward that player:
- Hostile — the faction considers the player an enemy. Entities in this faction will actively target the player and deal damage.
- Neutral — the faction neither attacks nor protects the player.
- Friendly — the faction considers the player an ally. Friendly-fire rules apply, and the player is protected from damage by same-faction entities unless the faction allows friendly fire.
Reputation can be set to an absolute value or adjusted by a delta, making it suitable for quest rewards, kill penalties, story triggers, and progressive reputation systems.
Parties
Parties are an independent grouping system separate from factions. They are designed for quests, dungeon instances, story events, and script-driven logic that needs to know "which players are currently grouped together."
Each party contains:
- Party ID — a unique, normalized identifier.
- Leader — the player who leads the party. If the leader leaves, the next member is automatically promoted.
- Member list — all players currently in the party.
- Friendly fire toggle — whether party members can damage each other.
A player can only belong to one party at a time. Joining a new party automatically leaves the previous one. Parties with no remaining members are automatically removed.
Inter-Faction Hostility
Hostility between factions is unidirectional. If you want faction A and faction B to be mutually hostile, you must add both directions:
A -> B does not automatically create B -> A.
This design allows asymmetric relationships, such as a faction that is hostile toward another but is not reciprocated.
Behavior Details
Name Tag Colors
The client renders entity name tags with color hints based on the viewing player's effective attitude toward the entity's faction:
| Attitude |
Color |
| Friendly |
Green |
| Neutral |
Yellow |
| Hostile |
Red |
The mod does not force name tags to appear. Visibility is still controlled by vanilla mechanics or other mods (e.g. CustomNameVisible, entity name display rules, NBT data set by map makers).
Name tag data is synchronized to clients on login, respawn, dimension change, and whenever faction/reputation data is modified. If the player is in a party, the effective attitude is calculated using the party's standing strategy.
Damage Rules
The mod intercepts damage events to enforce faction and party rules as a safety net, even when custom AI or other mechanisms bypass normal target selection:
- Same party — party members cannot hurt each other unless the party has friendly fire enabled.
- Same faction — entities in the same faction cannot hurt each other unless the faction allows friendly fire.
- Player vs. friendly faction — when a player has a Friendly attitude toward a faction, neither the player nor the faction's entities can damage each other unless the faction allows friendly fire.
- Neutral — neutral relationships do not provide damage protection, but entities will not actively target neutral players either.
- Hostile — damage is always allowed.
Mob Targeting
The mod injects a low-priority faction targeting goal into all Mob entities on the server side:
- Entities without a faction assignment are completely unaffected — no extra scanning overhead.
- Entities with a faction will:
- Actively target players who are Hostile toward their faction.
- Actively target entities belonging to enemy factions (if the faction's "attack enemy factions" toggle is enabled).
- Never target entities in the same faction.
- The targeting goal runs at a low priority, making it compatible with vanilla AI and most modded entities that use the standard goal system.
- A per-tick sanity check clears invalid targets and stops navigation if a mob is somehow targeting a protected entity.
For fully custom AI implementations, the mod provides FactionApi methods that can be called directly.
Party Effective Standing
Parties do not store their own faction reputation. Instead, effective standing is calculated dynamically from member reputations when the faction attitude needs to be determined.
The default strategy is min — the lowest reputation among all party members. This prevents a hostile player from joining a friendly party to bypass guard hostility, mob AI, dungeon access, or faction permissions.
Built-in strategies:
| Strategy |
Description |
Recommended Use |
min |
Lowest member reputation (default) |
Guard hostility, enemy detection, dungeon access control |
average |
Average member reputation, rounded down |
Settlement displays, soft evaluations |
leader |
Leader's reputation only |
Story triggers, quest entry points |
max |
Highest member reputation |
Special scripts where "anyone in the party knows this faction" is sufficient |
All vanilla/modded targeting, damage interception, and name tag colors use the default min strategy. Individual player reputations are always stored independently — the party is merely a runtime lens for evaluating faction relationships.
Data Persistence
All faction data, entity assignments, player reputations, and party memberships are stored in the world's saved data (attached to the overworld). This means:
- Data persists across server restarts.
- Deleting a faction automatically cleans up all associated entity assignments, player reputations, and enemy faction references in other factions.
- Party member changes are saved immediately.
评论 0
登录后参与评分
还没有评论,来抢沙发吧