Embedding Guide

Dogma is designed to be embedded in Rust host applications — games especially. The host controls everything: which functions scripts can call, which types they can use, and how many operations they may execute.

Scripts start with zero capabilities. The host grants exactly what it wants to expose, nothing more.

Quick example🔗

use dogma_vm::{Engine, engine::NativeSpec, value::Value};

let engine = Engine::builder()
    .with_capability_functions("myapp", vec![
        NativeSpec::new("greet", 1, |_engine, args| {
            let name = args[0].as_string()?;
            Ok(Value::String(format!("Hello, {name}!")))
        }),
    ])
    .with_max_operations(100_000)
    .build();

engine.run_file(std::path::Path::new("script.dg"))?;

See the full working example in examples/embedding/ in the repository.

Pages in this section🔗

• Engine Builder — Engine::builder() API
• Capability Functions — exposing host functions
• Native Types — exposing Rust values
• Resource Limits — capping script execution