Host Functions API Reference

entity_read(entity_type: string, entity_id: string) -> string

let json_str = host::entity_read("character", "aria-blackwood")?;
let entity: serde_json::Value = serde_json::from_str(&json_str)?;
let name = entity["name"].as_str().unwrap_or("Unknown");
let backstory = entity["_body"].as_str().unwrap_or("");

{
  "entity_type": "character",
  "entity_id": "aria-blackwood",
  "name": "Aria Blackwood",
  "role": "protagonist",
  "age": 28,
  "_body": "# Aria Blackwood\n\nA skilled navigator...",
  "_meta": {
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-20T14:30:00Z",
    "template": "character-standard"
  }
}

entity_list(query: string) -> string

let json_str = host::entity_list("entity_type=character&limit=10&sort=name")?;
let entities: Vec<serde_json::Value> = serde_json::from_str(&json_str)?;
for entity in &entities {
    let name = entity["name"].as_str().unwrap_or("Unknown");
    host::log("info", &format!("Found character: {}", name));
}

entity_create(entity_type: string, data: string) -> string

let data = serde_json::json!({
    "name": "New Character",
    "role": "supporting",
    "age": 35,
    "_body": "# New Character\n\nBackstory goes here."
});
let result = host::entity_create("character", &data.to_string())?;
let created: serde_json::Value = serde_json::from_str(&result)?;
let new_id = created["entity_id"].as_str().unwrap();

entity_update(entity_type: string, entity_id: string, content: string) -> string

let updates = serde_json::json!({
    "role": "antagonist",
    "age": 30
});
let result = host::entity_update("character", "aria-blackwood", &updates.to_string())?;

entity_delete(entity_type: string, entity_id: string) -> bool

let deleted = host::entity_delete("character", "old-character")?;
if deleted {
    host::log("info", "Entity deleted successfully");
}

asset_read(entity_type: string, entity_id: string, filename: string) -> bytes

let image_bytes = host::asset_read("character", "aria-blackwood", "portrait.png")?;
// Process image bytes (e.g., analyze, resize, convert)
let size = image_bytes.len();
host::log("info", &format!("Portrait size: {} bytes", size));

asset_write(entity_type: string, entity_id: string, filename: string, data: bytes) -> void

let generated_image: Vec<u8> = generate_portrait()?;
host::asset_write(
    "character",
    "aria-blackwood",
    "ai-portrait.png",
    &generated_image
)?;
host::ui_notify("Asset Uploaded", "AI portrait saved", "success");

http_request(url: string, method: string, headers: string, body: string) -> string

{
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"result\": \"ok\"}"
}

let headers = serde_json::json!({
    "Authorization": format!("Bearer {}", host::get_config("api_key")?),
    "Content-Type": "application/json"
});
let body = serde_json::json!({
    "query": "search term"
});
 
let response_str = host::http_request(
    "https://api.example.com/search",
    "POST",
    &headers.to_string(),
    &body.to_string()
)?;
 
let response: serde_json::Value = serde_json::from_str(&response_str)?;
let status = response["status"].as_u64().unwrap_or(0);
if status == 200 {
    let results = &response["body"];
    // Process results
}

ai_generate(prompt: string, model: string, options: string) -> string

let options = serde_json::json!({
    "max_tokens": 500,
    "temperature": 0.8,
    "system_prompt": "You are a creative writing assistant for game development.",
    "context_entities": ["aria-blackwood", "the-lost-city"]
});
 
let backstory = host::ai_generate(
    "Write a 3-paragraph backstory for this character based on their traits and location.",
    "creative",
    &options.to_string()
)?;
 
// Save the generated backstory to the entity
let update = serde_json::json!({
    "_body": backstory
});
host::entity_update("character", "aria-blackwood", &update.to_string())?;

ui_notify(title: string, message: string, level: string) -> void

host::ui_notify("Sync Complete", "15 entities synced with Jira", "success");
host::ui_notify("Warning", "API rate limit approaching", "warning");
host::ui_notify("Error", "Failed to connect to external service", "error");

get_config(key: string) -> string

let api_key = host::get_config("api_key")?;
let depth: usize = host::get_config("analysis_depth")
    .unwrap_or("3".to_string())
    .parse()
    .unwrap_or(3);
let auto_sync = host::get_config("auto_sync")? == "true";

set_config(key: string, value: string) -> void

host::set_config("last_sync_at", &chrono::Utc::now().to_rfc3339())?;
host::set_config("oauth_token", &token_response.access_token)?;

storage_get(key: string) -> string

let cached = host::storage_get(&format!("analysis/{}/{}", entity_type, entity_id))?;
if !cached.is_empty() {
    let data: serde_json::Value = serde_json::from_str(&cached)?;
    // Use cached data
}

storage_set(key: string, value: string) -> void

let analysis = serde_json::json!({
    "entity": entity_id,
    "related_count": related.len(),
    "analyzed_at": chrono::Utc::now().to_rfc3339()
});
host::storage_set(
    &format!("analysis/{}/{}", entity_type, entity_id),
    &analysis.to_string()
)?;

storage_delete(key: string) -> void

storage_list(prefix: string) -> string

let keys_json = host::storage_list("analysis/character/")?;
let keys: Vec<String> = serde_json::from_str(&keys_json)?;
host::log("info", &format!("Found {} cached analyses", keys.len()));

log(level: string, message: string) -> void

host::log("info", "Plugin initialized");
host::log("debug", &format!("Processing entity: {}", entity_id));
host::log("warn", "External API returned unexpected format");
host::log("error", &format!("Failed to parse response: {}", err));

#[export]
fn on_entity_created(entity: Entity) -> Result<(), PluginError> {
    // Each host call can fail
    let data = host::entity_read("character", entity.id())?;
    let response = host::http_request(
        "https://api.example.com/webhook",
        "POST",
        "{}",
        &data
    )?;
 
    // Check response status
    let resp: serde_json::Value = serde_json::from_str(&response)?;
    if resp["status"].as_u64() != Some(200) {
        host::log("error", "Webhook failed");
        return Err(PluginError::new("webhook_failed"));
    }
 
    Ok(())
}