Warp System

Warp is Thaumcraft’s madness/taint mechanic. Using certain items, completing research, or crafting specific things adds temporary, permanent, or sticky warp to a player. High warp causes various negative effects.

Warp Types

Type	Description	Removal
Temporary	Decays over time naturally.	Automatically removed over time.
Permanent	Never decays. Accumulates indefinitely.	Cannot be removed.
Sticky	Permanent warp that can be manually removed.	Can be reduced by using specific items.

⚠️ 订正/来源声明

• 原表 Temporary 一栏写「~5 minutes per point」——无法核实，本仓源码中没有任何衰减速率或时间常量。已删除该数字。
• 原表与正文提到「Amulet of Warding」可移除 sticky warp——无法核实。源码只说 「Sticky warp is permanent warp that can be removed」（ThaumcraftApiHelper.java:251-252）， 未指名任何道具。具体道具属主 mod 内容，不在本 API 仓内。 （另注：同仓 ../item-effect/warp-system 曾把同一机制写成「Salting Mundane」， 两处互相矛盾，都不可核实，此处统一按源码改为不指名道具。）
• 三种 warp 的划分本身有源码依据：addWarpToItem 的 javadoc 明说「The warp added is "sticky" warp」 （ThaumcraftApi.java:437-438），addWarpToResearch 明说是「permanent warp」（ThaumcraftApi.java:447-448）， addWarpToPlayer 的 temporary 布尔参数区分 temporary / permanent（ThaumcraftApiHelper.java:241-247）。

---

Warp Registration

addWarpToItem

ThaumcraftApi.addWarpToItem(ItemStack craftresult, int amount)

Adds sticky warp to a player when they craft the specified item.

// When a player crafts the resulting item, they gain 'amount' sticky warp
ThaumcraftApi.addWarpToItem(new ItemStack(ModItems.myCursedItem), 3);

Parameter	Type	Description
craftresult	ItemStack	The crafted item. Both item and metadata are matched.
amount	int	Amount of sticky warp gained.

addWarpToResearch

ThaumcraftApi.addWarpToResearch(String research, int amount)

Adds permanent warp to a player when they complete the specified research.

// Player gains 2 permanent warp upon completing "MY_RESEARCH"
ThaumcraftApi.addWarpToResearch("MY_RESEARCH", 2);

Parameter	Type	Description
research	String	The research key (must match exactly).
amount	int	Amount of permanent warp gained.

getWarp

ThaumcraftApi.getWarp(Object in)

Returns how much warp is associated with an item or research.

int warp = ThaumcraftApi.getWarp(new ItemStack(ModItems.myItem));
int warp = ThaumcraftApi.getWarp("MY_RESEARCH");

Parameter	Type	Description
in	ItemStack or String	The item or research key.

Returns 0 if nothing is registered.

---

Runtime Warp Management

addWarpToPlayer

ThaumcraftApiHelper.addWarpToPlayer(EntityPlayer player, int amount, boolean temporary)

Adds temporary or permanent warp to a player at runtime (e.g. when using an item or casting a spell).

// Add 1 temporary warp point
ThaumcraftApiHelper.addWarpToPlayer(player, 1, true);

// Add 2 permanent warp points
ThaumcraftApiHelper.addWarpToPlayer(player, 2, false);

Parameter	Type	Description
player	EntityPlayer	The target player.
amount	int	Amount of warp to add. Negative values only valid for temporary warp.
temporary	boolean	true for temporary warp, false for permanent.

addStickyWarpToPlayer

ThaumcraftApiHelper.addStickyWarpToPlayer(EntityPlayer player, int amount)

Adds sticky warp to a player. Sticky warp is permanent warp that can be removed.

// Add 1 sticky warp point
ThaumcraftApiHelper.addStickyWarpToPlayer(player, 1);

// Remove 1 sticky warp point
ThaumcraftApiHelper.addStickyWarpToPlayer(player, -1);

Parameter	Type	Description
player	EntityPlayer	The target player.
amount	int	Amount (positive adds, negative removes).

Sync

All warp changes are automatically synced to the client-side player state.

---

IWandable and Warp

The IWandable interface allows tile entities to respond to wand interactions. While not strictly a warp interface, wand interactions can be used to implement warp-related mechanics (e.g. a warp-generating wand effect that adds warp on use).

See Wand Triggers for more on IWandable.

---

Warp Effects

High warp causes various negative effects on the player:

• Taintment Mobs: Spawn around players with high warp.
• Wandering Trader: May refuse to deal with high-warp players.

⚠️ 已订正：原列表中「Vis Discount: Players with high warp have reduced vis costs」——方向反了、且无源码依据。 本仓唯一与 vis 折扣相关的 API 是 IVisDiscountGear.getVisDiscount(ItemStack) （见 ../item-effect/vis-discount），该接口与玩家 warp 值毫无关系， 全仓 grep 无任何把 warp 状态接入 vis 折扣的代码。已删除该条。

「Research Penalty: High warp can cause research to fail or produce taint aspects」—— 无法核实，本仓无相关代码（addWarpToResearch 只在研究完成时按 warpMap 发放 warp， 不反向影响研究流程，证据：ThaumcraftApi.java:451-453）。已删除该条。

剩余两条（污秽生物、行商拒绝交易）同样无法从本仓核实，属主 mod 行为，保留但标注如上。

---

Example: Warp-Generating Crafting Recipe

// In your mod's init
public void registerWarp() {
    // Any player who crafts myWandOfDoom gains 3 sticky warp
    ThaumcraftApi.addWarpToItem(new ItemStack(Item.getByNameOrId("mymod:wand_of_doom")), 3);
}

Example: Warp-Gaining Spell Effect

// In a focus or wand effect
public void onPlayerStoppedUsingFocus(ItemStack wandstack, World world, EntityPlayer player, int count) {
    // Applying a "dark" spell costs the player 1 temporary warp
    ThaumcraftApiHelper.addWarpToPlayer(player, 1, true);
}

Example: Research Warp

// In your research registration
public void registerResearchWarp() {
    // Completing "ELDRITCH_LORE" grants 5 permanent warp
    ThaumcraftApi.addWarpToResearch("ELDRITCH_LORE", 5);
}