Discord
@hash/cranes
Behavior
4
0
Public

Crane Library

The Crane Library is part of the Material Handling Libraries. Cranes allow you to pick up and move items within bounded areas. You can find further information about them in the HASH docs.
forked from @hash/crane

The Crane Library is part of the Material Handling Libraries. You can find further information about them in the HASH docs.


Cranes allow you to pick up and move items within bounded areas. They can generally move without interference since they can be located above the level of other agents.

Defining a Crane

You can define your crane as either a Jib or Overhead crane. Jib cranes will rotate (change their direction) to move the agent they are carrying, while Overhead cranes will change their position as they carry their cargo.

Crane Demonstration An Overhead crane (green) and Jib crane (blue)

Behaviors

All cranes make use of the @hash/crane/store_instructions.js to interpret the messages they receive and add them to a queue of instructions which persists between timesteps.

Each type of crane has a corresponding behavior which fulfills its instructions. This includes picking and placing agents, and the timing of those actions. The corresponding _move.js behaviors visualize the movement of the cranes (linear or rotational) more realistically. You can always substitute your own behaviors with the published library ones.

A full example behavior chain for a jib crane could look like this:

[
  "@hash/crane/store_instructions.js",
  "@hash/crane/jib.js",
  "@hash/crane/jib_move.js"
]

Parameters

Crane parameters are specified in the agent's state as state.crane_parameters. Crane agents with @hash/crane/store_instructions.js must have instruction_message_filter defined, while agents without it only need time.

"crane_parameters": {
  "instruction_message_filter": string, // The message type a crane will interpret as instructions
  "time": {
    "pick": 5, // The time it takes the crane to pick up an agent
    "move": 10, // The time it takes the crane between picking an agent to placing it
    "place": 3 // The time it takes the crane to place an agent
  }
}

Instead of assigning a set time it takes for a crane to move between locations, you can set the speed at which the crane moves or rotates. On Overhead cranes this can be set with the crane_parameters.speed field, and with Jib cranes the crane_parameters.rotation_speed field. You no longer need to include the time.move field if you've assigned a speed.

Interacting with a Crane

Cranes perform actions based on instructions stored in their state.instructions array. The instruction must be formatted as:

{
  "agent_definition": struct, // The full definition of the agent to be picked up
  "pick_position": number[], // The position the agent will be picked from
  "place_position": number[] // The position the agent will be placed at
}

If instructions are being sent to the crane through messages, the message must have a type that matches the string defined in state.crane_parameters.instruction_message_filter.

Pickup Logic

When a crane picks up another agent, it temporarily removes that agent from the simulation state, and stores it within its own state. When it places the agent, it is added back to the simulation state. The agent is identical to the one that was picked, except for a change in its position. This means that no behaviors on the agent were run during the time it was being moved.