Contraptify

Run a redstone design with its own test (inputs and expectations) and return which expectations hold and which fail (with what the block was instead, and when), what visibly changed (lamps, pistons, doors, dispensers) and when, dispenser shots, and notes on what broke. Without a test it just runs the machine and reports what changed. Use it on every candidate before showing it. Do not use it to display a design to the user: use show.

{
  "type": "object",
  "properties": {
    "design": {
      "type": "object",
      "description": "A machine: a list of blocks plus what it is for. See the server instructions for block types and rules.",
      "properties": {
        "name": {
          "type": "string",
          "description": "2-5 word name"
        },
        "test": {
          "type": "object",
          "description": "Your test for this design (see TESTING in the instructions). Tick 0 is the machine once built; inputs at tick t happen after t game ticks, and expectations for tick t are checked right after them.",
          "properties": {
            "ticks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6000,
              "description": "How long to run (default: 60 ticks after the last input or expectation, at least 100)"
            },
            "inputs": {
              "type": "array",
              "description": "What a player does: {tick, do, at: [x,y,z]}. do: pull (lever), press (button), use (wooden door, wooden trapdoor or fence gate; optional look), stand (step onto a pressure plate or string), leave (step off), throw (a snowball at a target), turn_page (lectern), toggle (daylight detector), start (place a block against the observer marked \"start\": true; no at), place_cart (put a minecart on a rail)",
              "items": {
                "type": "object"
              }
            },
            "expect": {
              "type": "array",
              "description": "What must be true: {at: [x,y,z], tick, is: {field: value}} or {at, from, to, is} (every tick from..to). Fields: type, shape (rails), on, lit, open, powered, extended, level, power, phase, locked, attached, inverted, facing, out (a comparator's output), count (items in a container). Or {shots: {min, max}, from, to, at?} for dispenser shots.",
              "items": {
                "type": "object"
              }
            }
          }
        },
        "time": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23999,
          "description": "Time of day at the start, 0-23999 (6000 = noon, the default); only daylight detectors use it"
        },
        "summary": {
          "type": "string",
          "description": "One or two plain sentences: how it works and how to use it"
        },
        "parts": {
          "type": "object",
          "description": "Part key -> {name, text}: what each part does, shown when the user clicks it",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "blocks": {
          "type": "array",
          "description": "Block objects: {type, x, y, z, ...fields, part}",
          "items": {
            "type": "object"
          }
        },
        "view": {
          "type": "object",
          "description": "Optional starting camera for show, when the part to watch is small in a large machine: {target: [x,y,z] to look at, from: [x,y,z] the camera position}. Default: the whole machine.",
          "properties": {
            "target": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "from": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          }
        }
      },
      "required": [
        "blocks"
      ]
    }
  },
  "required": [
    "design"
  ]
}

List a design's parts with their explanations, how many blocks each covers, and any blocks without a part. Use it before show to make sure every block is explained. Do not use it to test whether the machine works: use simulate.

{
  "type": "object",
  "properties": {
    "design": {
      "type": "object",
      "description": "A machine: a list of blocks plus what it is for. See the server instructions for block types and rules.",
      "properties": {
        "name": {
          "type": "string",
          "description": "2-5 word name"
        },
        "test": {
          "type": "object",
          "description": "Your test for this design (see TESTING in the instructions). Tick 0 is the machine once built; inputs at tick t happen after t game ticks, and expectations for tick t are checked right after them.",
          "properties": {
            "ticks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6000,
              "description": "How long to run (default: 60 ticks after the last input or expectation, at least 100)"
            },
            "inputs": {
              "type": "array",
              "description": "What a player does: {tick, do, at: [x,y,z]}. do: pull (lever), press (button), use (wooden door, wooden trapdoor or fence gate; optional look), stand (step onto a pressure plate or string), leave (step off), throw (a snowball at a target), turn_page (lectern), toggle (daylight detector), start (place a block against the observer marked \"start\": true; no at), place_cart (put a minecart on a rail)",
              "items": {
                "type": "object"
              }
            },
            "expect": {
              "type": "array",
              "description": "What must be true: {at: [x,y,z], tick, is: {field: value}} or {at, from, to, is} (every tick from..to). Fields: type, shape (rails), on, lit, open, powered, extended, level, power, phase, locked, attached, inverted, facing, out (a comparator's output), count (items in a container). Or {shots: {min, max}, from, to, at?} for dispenser shots.",
              "items": {
                "type": "object"
              }
            }
          }
        },
        "time": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23999,
          "description": "Time of day at the start, 0-23999 (6000 = noon, the default); only daylight detectors use it"
        },
        "summary": {
          "type": "string",
          "description": "One or two plain sentences: how it works and how to use it"
        },
        "parts": {
          "type": "object",
          "description": "Part key -> {name, text}: what each part does, shown when the user clicks it",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "blocks": {
          "type": "array",
          "description": "Block objects: {type, x, y, z, ...fields, part}",
          "items": {
            "type": "object"
          }
        },
        "view": {
          "type": "object",
          "description": "Optional starting camera for show, when the part to watch is small in a large machine: {target: [x,y,z] to look at, from: [x,y,z] the camera position}. Default: the whole machine.",
          "properties": {
            "target": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "from": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          }
        }
      },
      "required": [
        "blocks"
      ]
    }
  },
  "required": [
    "design"
  ]
}

List the built-in example designs (clocks, counters, a piston door, a lock, a flying machine). Use it to find a known-good starting point. Do not use it to fetch a design's blocks: use get_example.

{
  "type": "object",
  "properties": {}
}

Return one built-in example design with its blocks, part explanations and its own test, by id from list_examples. Large designs (the 0-9 counter has about 2,500 blocks, the 00-59 clock about 5,100) are long. Do not use it to show an example to the user: use show with example set.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Show a design to the user in an interactive 3D viewer in the chat: they can press its button or flip its lever, watch it run tick by tick, move around, and click any part to read what it does. Give either design, or example (an id from list_examples). Call it once per answer, at the end, after the last simulate passes: every call adds another viewer to the chat. Do not use it to test a design: use simulate.

{
  "type": "object",
  "properties": {
    "design": {
      "type": "object",
      "description": "A machine: a list of blocks plus what it is for. See the server instructions for block types and rules.",
      "properties": {
        "name": {
          "type": "string",
          "description": "2-5 word name"
        },
        "test": {
          "type": "object",
          "description": "Your test for this design (see TESTING in the instructions). Tick 0 is the machine once built; inputs at tick t happen after t game ticks, and expectations for tick t are checked right after them.",
          "properties": {
            "ticks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6000,
              "description": "How long to run (default: 60 ticks after the last input or expectation, at least 100)"
            },
            "inputs": {
              "type": "array",
              "description": "What a player does: {tick, do, at: [x,y,z]}. do: pull (lever), press (button), use (wooden door, wooden trapdoor or fence gate; optional look), stand (step onto a pressure plate or string), leave (step off), throw (a snowball at a target), turn_page (lectern), toggle (daylight detector), start (place a block against the observer marked \"start\": true; no at), place_cart (put a minecart on a rail)",
              "items": {
                "type": "object"
              }
            },
            "expect": {
              "type": "array",
              "description": "What must be true: {at: [x,y,z], tick, is: {field: value}} or {at, from, to, is} (every tick from..to). Fields: type, shape (rails), on, lit, open, powered, extended, level, power, phase, locked, attached, inverted, facing, out (a comparator's output), count (items in a container). Or {shots: {min, max}, from, to, at?} for dispenser shots.",
              "items": {
                "type": "object"
              }
            }
          }
        },
        "time": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23999,
          "description": "Time of day at the start, 0-23999 (6000 = noon, the default); only daylight detectors use it"
        },
        "summary": {
          "type": "string",
          "description": "One or two plain sentences: how it works and how to use it"
        },
        "parts": {
          "type": "object",
          "description": "Part key -> {name, text}: what each part does, shown when the user clicks it",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "blocks": {
          "type": "array",
          "description": "Block objects: {type, x, y, z, ...fields, part}",
          "items": {
            "type": "object"
          }
        },
        "view": {
          "type": "object",
          "description": "Optional starting camera for show, when the part to watch is small in a large machine: {target: [x,y,z] to look at, from: [x,y,z] the camera position}. Default: the whole machine.",
          "properties": {
            "target": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "from": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          }
        }
      },
      "required": [
        "blocks"
      ]
    },
    "example": {
      "type": "string",
      "description": "Id of a built-in example to show instead of a design"
    }
  }
}