DOCSEARCHbyAlgolia
Submit Docs

HSAPI Documentation

website·Indexed 30 days ago

https://hsapi.dev

A low-level transpiler for parsing and writing .hopscotch project files. HSAPI provides tools for Hopscotch hacking projects, including specifications for project JSON structures, blocks, abilities, and the Hopscript language.

Tokens
6.6K
Snippets
35
Records
60
Agent score
50%

What's inside HSAPI

  1. Overview of HSAPI

    HSAPI is a low-level transpiler designed for parsing and writing .hopscotch project files. It is currently under active development.

  2. Overview of HSAPI capabilities

    HSAPI is a toolbox for Hopscotch development that provides full API coverage for blocks, rules, and variables, including support for custom blocks and presets. It features a Rust backend that allows it to be embedded across various platforms, including mobile web browsers and desktop tools. Key use cases include creating custom blocks and implementing mass block placement.

  3. Understand the Hopscotch project file structure

    Hopscotch projects are stored as JSON files (with the .hopscotch extension on mobile apps). The data is organized in a hierarchical container system:

    • Scenes: Contain a list of unique object identifiers (IDs).
    • Objects: Contain a list of IDs referencing rules and custom rule instances.
    • Custom Rule Instances: Contain a reference to a custom rule and its associated parameters. These share the same properties as objects.
    • Rules: Contain an ID referencing an ability.
    • Abilities: Contain blocks, which can recursively contain other abilities or parameters.

  4. Understand Block object properties

    Blocks are objects used within abilities and as the datum property of parameters. They share a set of common properties that define their behavior and classification.

  5. Understand Hopscript design goals and objectives

    Hopscript is designed to provide a textual representation of Hopscotch code. Its primary objectives are to represent any Hopscotch code textually, remain intuitive for users familiar with Hopscotch, and provide a simple bidirectional interface with existing Hopscotch code.

    Secondary goals include:

    • 1:1 Dehopscotchification: The ability to convert Hopscotch code to Hopscript and back to identical code (excluding internal IDs).
    • User-definable blocks: Support for custom blocks to facilitate modding.
    • Name shadowing resolution: The compiler must unambiguously differentiate between local variables and blocks, even when they share names (e.g., a variable named and vs. a block named and).
    • Extensibility: The system is designed to be easily extended.

  6. Use the datum property for dynamic parameter values

    The datum property determines the data contents of a parameter, allowing it to be more than a static value. When a datum is present, it typically overrides the value property. The player resolves datum objects in this priority order:

    1. Images (within Set Image blocks)
    2. Variable references
    3. Traits and blocks

    A datum can contain:

    • An operator block (e.g., Math or Color operators)
    • A trait
    • A variable reference
    • An image (specifically for Set Image blocks)

  7. Control editor requirements and app versioning

    Two root properties control how the project is opened and edited:

    • requires_beta_editor (boolean): If true, the project was saved with the advanced editor and requires a Hopscotch subscription to edit.
    • version (number): The latest Hopscotch app version used to save the project. Projects will not open in app versions older than this value. If version <= 24, the app uses the old player instead of the web player.
    "requires_beta_editor": true,
"version": 34

  8. Dehopscotchify names in hopscript

    Names are dehopscotchified by reversing the process described in name hopscotchification. If a dehopscotchified name cannot be re-hopscotchified back to its original form, the compiler will use the string literal form of the name to ensure fidelity.

  9. Implement modifier extensions for the Hopscript compiler

    Modifier extensions allow for substantial changes to language behavior, such as defining new scopes or modifying hopscotchified code. These are written as Hopscript files targeting a custom interpreter rather than the Hopscotch player. They can use hsapi calls to modify the output of the hopscotchification process. Extensions must be explicitly opted-into by the files they affect.
    # Example of defining a Scope as an object type in an extension
Scope Game:
	When i_am_used:
		# Use the `Rule` scope to refer to arguments
		hsapi_create_variable(named: Rule.variable_name, type: HSBlockType.Game, store_into: result)
		return(result)

# Example of an enum extension
enum HSBlockType:
	...
	Game = 8003
	...

  10. Define basic block and object types in Hopscript

    Because the hopscotchifier/compiler does not inherently know what block types are, they must be defined within Hopscript using specific definition commands. These definitions allow the compiler to understand how to handle different blocks, objects, and traits.

  11. Define and reference custom blocks and rules

    Custom blocks and rules are defined using the syntax <type> <name> [parameters]:.

    • Definitions: If defined at the top level, they are made available for use elsewhere. Parameters in top-level definitions must be literal values (defaults).
    • References: To use a custom block or rule without defining it, reference it without the trailing colon: Custom_block <name> [parameters] or Custom_rule <name> [parameters].
    • Context: Defining a custom block within a context where it can be referenced (like an ability) both defines the block and adds a reference to it.
    # Definition
Custom_block do_something(argument: "Default value", arg2: 0):
	# block logic here

# Reference (used inside another block)
Custom_rule make_a_grid(width: 5, height: 5)

  12. Configure the beta editor requirement

    Use _setRequiresBetaEditor to set the requires_beta_editor value in the project JSON. This is required for advanced mode files to accurately recreate app behavior.
    _setRequiresBetaEditor <boolean>