hCore Message API

hCore provides a messaging API for embedded instances of hCore. You can use the messaging API to edit and set a simulation files and to read the state of a simulation. We'd love your feedback on this feature.

See the hCore Messaging API in action in the Create a Simulation Dashboard tutorial.

All hCore messages use the postMessage technique for messaging between iFrames. In order to send a message, create a webpage which loads hCore in an iframe, and then send a message to that iframe.

//example
<iframe>.contentWindow.postMessage({
id: <unique id, string>,
type: <message type, string>
},
"*"
);

updateFile

Update the contents of a simulation file to the contents defined in the message payload.

updateFile message example
{
"id": "1625b2ce-441f-4b42-8d44-80ec3bae2495",
"type": "updateFile",
"file": "globals.json",
//stringify the contents and HASH will auto decode.
"contents": JSON.stringify({"foo": 1})
}

sendState

Request the current state of the simulation. Will return a message with type: "state" and the full state as a dictionary under contents, where the key is the time step and the value an array of agent objects.

Message
Response
Message
sendState message example
{
"id": "1625b2ce-441f-4b42-8d44-80ec3bae2495",
"type": "sendState"
}
Response
{ type: 'state',
contents:
{ steps: { 0: [Array], 1: [Array] },
stepsCount: 2,
simulationRunId: 'eb42f23b-b6b2-4fd2-89ea-5e8fd9e61e9e',
startedTime: 1622587139503,
plots: null,
experimentId: null,
status: 'queued',
mode: 'computeAndPlayback',
presentingSpeed: 'live',
presenting: false,
scrubbedStep: null,
owedSteps: 0 }
}

initialize

Request that HASH send a message every time a file changes. If you send this to a framed hCore, it will send a message with type: "files" and content: file[] every time changes are made to a source file.

Message
Message
initialize message example
{
"id": "1625b2ce-441f-4b42-8d44-80ec3bae2495",
"type": "initialize"
}

resetAndRun

Trigger hCore to reset the simulation, generate a new simulation run, and start it playing.

Message
Message
resetAndRun message example
{
"id": "1625b2ce-441f-4b42-8d44-80ec3bae2495",
"type": "resetAndRun"
}