Skip to content

A framework for creating WebAssembly Etheryal extensions

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

etheryal/extension-rust

etheryal WebAssembly Extensions 💖

A framework for creating WebAssembly (WASI) modules for etheryal extensions in the Rust programming language, enabling the creation of custom functionality like advanced universe generation, custom creature AI, registering commands, and more! All module extensions are loaded at runtime, and can be enabled or disabled at any time.

If you don't need advanced functionality, you can also create a simple extension with an etheryal.toml file and the data-oriented extension system.

Getting Started

Prerequisites

Installation

  1. Create a new Rust project:

    cargo new my-extension
  2. Add the following to your Cargo.toml file:

    [dependencies]
    etheryal-extension = { git = "https://github.com/etheryal/extension-framework.git" }
    bevy_app = "0.11"
    bevy_ecs = "0.11"
  3. Add the following to your main.rs file (see the full example here):

     pub fn main() {
         // Create the extension module info, which will be used to register the
         // extension module with the etheryal Server
         let extension_info = ExtensionModuleInfo::builder()
             .name("Example Extension Module".into())
             .identifier(NamespacedIdentifier::try_from("example:extension_module").unwrap())
             .version(Version::new(0, 1, 0))
             .dependencies(vec![
                 // Require a specific version of the etheryal Server
                 ExtensionModuleDependency::builder()
                     .identifier(NamespacedIdentifier::new(
                         // The namespace of the etheryal Server
                         Identifier::default(),
                         // The identifier of the etheryal Server
                         Identifier::default(),
                     ))
                     .version(VersionReq::parse(">=0.1.0-nightly").unwrap())
                     .build(),
             ])
             .build();
         App::new()
             .add_plugin(ScheduleRunnerPlugin::default())
             .add_plugin(etheryalExtensionPlugin::new(extension_info))
             .add_systems(Startup, setup)
             .add_systems(Update, events)
             .run();
     }
    
     /// This system will be called when the extension starts
     fn setup(guest: Res<ExtensionGuest>) {
         println!("Extension guest started");
    
         // Send a ping message to the etheryal server
         guest.send_message(Ping).ok();
     }
    
     /// This system will be called when the extension receives a pong message from
     /// the etheryal server
     fn events(mut events: EventReader<ExtensionEvent<Pong>>, guest: Res<ExtensionGuest>) {
         for _ in events.iter() {
             println!("Received pong message");
    
             // Request the etheryal server to shutdown
             guest.send_message(ShutdownHost).ok();
         }
     }
  4. Build your extension module:

    cargo wasi build --release
  5. Go to the extensions directory of your etheryal server and create a new directory for your extension module. Inside this directory, create a etheryal.toml file with the following contents:

    name = "Example Extension"
    id = "example_extension"
    description = "An example etheryal extension with a WebAssembly module"
    author = "Your Name"
    version = "0.1.0"
    license = "MIT"
  6. Copy your extension module to the directory you created in step 4. You can find your compiled .wasm module in the target/wasm32-wasi/release directory.

  7. Start your etheryal server.

License

Except where noted (below and/or in individual files), all code in this repository is dual-licensed under either:

Contributing

When interacting with the open-source etheryal projects, please follow our Code of Conduct. If you'd like to contribute to this project, please read the Contributing Guide.

About

A framework for creating WebAssembly Etheryal extensions

Topics

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published