Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

0.15.0 - Asset Handles and Context Policies

This release focuses on aligning bevy_mod_scripting with modern Bevy practices, most notably by switching to Handle<ScriptAsset> for script management. This change simplifies the API, removes boilerplate, and makes script handling more idiomatic.

Summary

Asset-First Workflow

Scripts are now treated as first-class Bevy assets. The old ScriptId (which was a string) has been replaced by AssetId<ScriptAsset>, and you'll primarily interact with scripts via Handle<ScriptAsset>.

// New way
let handle: Handle<ScriptAsset> = asset_server.load("my_script.lua");
commands.spawn(ScriptComponent(vec![handle]));

Scripts are now only evaluated when they are attached to a ScriptComponent or added to StaticScripts, which means you have more control over when and how scripts are executed.

Flexible Context Policies

You now have much finer control over how script contexts (i.e., the environment a script runs in) are created. The old enable_context_sharing() has been replaced with set_context_policy() which accepts a ContextPolicy:

  • ContextPolicy::shared(): All scripts run in one global context
  • ContextPolicy::per_script(): Each script asset gets its own context (the old default.)
  • ContextPolicy::per_entity(): Each entity with scripts gets its own context.
  • ContextPolicy::per_entity_and_script(): A unique context for every script on every entity (the new default).

This means that each script is maximally isolated by default, but you can still opt for shared contexts if needed.

Other Changes

  • Recipients Enum: The Recipients enum for events has been redesigned to align with the new context policies, offering AllScripts and AllContexts variants, and removing some variants which don't fit the new model. If you need the old behaviour, you can simply query the ECS first before sending events.
  • API Cleanup: Several types and traits were removed or simplified, including ScriptAssetSettings, AssetPathToScriptIdMapper, and ScriptMetadataStore, as they are no longer needed with the new asset-based approach.

Migration Guide

This release contains significant breaking changes. Please refer to the migration guide for detailed instructions on updating your project.