Creating Custom Blocks (Legacy)

This method of adding blocks is deprecated and will be removed in Piecewise 22.07.0. To add custom blocks to Piecewise, use a plugin.

Those wishing to extend Piecewise can do so via custom blocks. To start, you’ll just need a block definition for the block you want to add. You can build a block using Blockly’s Block Factory here. Then, create a .js file in the addons folder containing a callback that returns a block property with your block definition, and a generator function that will generate the JavaScript code. Blockly is available via the first argument of the callback, but you should not register blocks yourself as Piecewise will handle making sure your block shows up in the Toolbox (as long as you define a category field on your block definition). Here’s an example of a custom block:

((Blockly) => {
    return {
        block: {
            "type": "discord_event_guild",
            "message0": "%1 🔔 server",
            "args0": [
                {
                    type: "field_image",
                    src: logo,
                    width: 15,
                    height: 15,
                    alt: "Discord",
                    flipRtl: false
                }
            ],
            "output": "discord_guild",
            "doc_output": "The server that is the target of this event.",
            "colour": 230,
            "tooltip": "The server that is the target of this event.",
            "inputsInline": true,
            "category": "Discord/Events",
            "onlyValidInside": [ "discord_when", "discord_command_create", "discord_interaction_button", "discord_interaction_dropdown", "discord_chat_command" ],
            "onlyValidEvents": [
                "discord_interactible",
                "discord_thread_created",
                "discord_thread_deleted",
                "discord_thread_leave",
                "discord_thread_join",
                "discord_channel_created",
                "discord_channel_deleted" // a bunch more... I have a system within Piecewise to track these
            ]
        },
        generator: block => {
            return [ `Lazurite.extract(ev, null, "guild") || lazurite.exception("event guild block was found, but was not attached to a valid event")`, Blockly.JavaScript.ORDER_NONE ]
        }
    }
}
});

Special properties

Piecewise extends the default Blockly block schema with a few extra properties.

block.onlyValidInside

Specify a list of blocks that this block is only valid inside. This extends all the way to the root (i.e. top) block. You may want to use this when writing your own event blocks, where the value a block returns is only valid within the event blocks.

Users will receive a warning if the block’s placement does not fulfill this condition.

block.onlyValidEvent

If one of the onlyValidInside blocks ends in _when, Piecewise will also check the event field and make sure the value matches this one.

Users will receive a warning if the block’s placement does not fulfill this condition.

block.weight

Determines how the block is weighted when determining position. If a weight isn’t specified, the default is zero.

block.restrictedWords

If a user-defined variable name or function matches this term, it will automatically be renamed in-code. This is useful for private variables you might declare, that you don’t want the user to be able to overwrite.

block.maxBlockCount

Defines how many of the block the user can use in the entire project. This makes sense for things like configuration blocks, where there should only be one.

block.onchange(block, event, projectIsLoading)

Defines a callback function to run when “something” happens to a block of this type. Use the projectIsLoading parameter to determine whether this is an event that occurs when the project is finished loading to filter out the creates/moves/etc that happen before then.

Special notes

• If users plan on distributing projects created with addons, they will need to distribute the addon files as well or the file will fail to load.
• Piecewise looks in the addons folder aside Piecewise.exe or Piecewise on Windows and Linux, or in ~/Library/Application Support/Piecewise/.lazurite on macOS.