Fabric Carpet Documentation

Fabric Carpet is a technical mod for vanilla Minecraft that provides fine-grained control over game mechanics. Key capabilities include:

• Time Manipulation: Use /tick warp to accelerate game time (e.g., testing farms) as fast as your hardware allows.
• Technical Monitoring:
  • Use /log to see live updates for server mobcap, TPS, and other metrics.
  • Use hopperCounters to get a detailed breakdown of items produced by hoppers.
• Mechanic Tweaks:
  • movableBlockEntities: Allows pistons to push block entities like chests.
  • Various bug fixes (e.g., leadfix, portalsuffocationfix, unloadedentityfix).

In Scarpet, entities are interacted with using two primary functions:

• query(e, 'property'): Retrieves information about an entity e.
• modify(e, 'property', value): Alters a property of entity e.

Syntax Alias: You can use the ~ operator as a shorthand for query. This is particularly useful for cleaner code when a statement has no extra arguments.

// Shorthand examples
query(p, 'name') <=> p ~ 'name'
query(p, 'holds', 'offhand') <=> p ~ ['holds', 'offhand']

The Carpet ecosystem consists of the core mod and several extensions:

• Core Carpet: The primary mod for technical control. Available on releases.
• carpet-extra: An add-on mod providing additional features like autocrafting, block-placing dispensers, and chicken-shearing.
• scarpet app store: A collection of apps written in the scarpet language. You can browse or contribute at https://github.com/gnembon/scarpet.
• quick-carpet: A minimal build for when you need basic functionality quickly (e.g., during Minecraft snapshots) but cannot wait for a full release. Note: quick-carpet does not support extensions or scarpet apps.
• Community Extensions: A list of other community-created extensions can be found on the Carpet Wiki.

Scoping

• Pass-by-value: All function parameters are passed by value, not by reference. Modifying a parameter inside a function does not change the original variable in the caller's scope.
• Global vs Local: Variables starting with global_ are global; all others are local to the function.

Capturing Outer Variables

To allow a function to 'borrow' or capture variables from the outer scope (similar to capturing lambdas in Java), use the outer() built-in function in the function signature.

When using outer(var), Scarpet attaches the value of the variable at the time of the function definition. For mutable types like maps or lists, the function can maintain state and act like an object because the reference to the mutable structure is preserved.

Assignment

• =: Standard assignment.
• +=: On a list, this extends the list with the new element(s).
• <>: Requires bounded arguments (variables) on both sides.
• List Destructuring: You can assign list elements to multiple variables: [a, b, c] = [1, 2, 3] results in a=1, b=2, c=3.

Unpacking (...)

The ... operator unpacks an iterator (list or map) into a sequence of arguments.

• In Functions: Identifies a vararg parameter.
• In Lists/Maps: Allows spreading elements into a new collection.

Warning: Unpacking is ignored in certain contexts like map(list, expr) or if(...) where expressions are expected instead of argument lists.

Most inventory-related functions require an inventory argument. You can specify the inventory using an entity, a block, or coordinates. You can also prefix the argument with an inventory type:

• null (default): The standard inventory (e.g., player's main inventory, or an entity's default inventory).
• 'enderchest': Accesses a player's enderchest storage.
• 'equipment': Accesses an entity's hand and armor pieces.

Examples:

• inventory_size('enderchest', player()) accesses the player's enderchest.
• inventory_size('equipment', player()) accesses the player's armor and held items.
• inventory_size(x, y, z) accesses a block inventory at those coordinates.
• inventory_size(block(pos)) accesses a block inventory at a specific position.

If the entity or block does not have an inventory, functions typically return null and do nothing.

Custom Events

• Programmers define and trigger these.
• They pass a single value as an argument (though this value can be a complex list, map, or NBT tag).
• They can be targeted to specific players or globally.

Built-in Events

• Provided by the system (e.g., tick, player_breaks_block).
• They have predefined argument structures.
• They target global apps by default because their first argument is clearly defined.

Event Scoping Summary