Matter v0.8.5

Matter v0.8.5 is our first LTS release. As we work toward v0.9.0 with our v0.9.0-beta.0 pre-release, we've committed to providing continued support for v0.8. Alongside the pre-releases this can help projects migrate on their own schedule in order to accommodate the changes being made. See the pre-release for details.

Added

• Systems can be sorted by run time via debugger button for better performance profiling. Thanks to @jackTabsCode in #150

Fixed

• The query cache has been updated so it can no longer skip archetypes in some cases. Thanks to @memorycode and @TheyCallMeRyan in #137
• The debugger now correctly and gracefully handles and displays cyclic tables. Thanks to @jackTabsCode in #148

For more details, view the full changelog, or check out our documentation.

Matter v0.9.0-beta.0

We’re excited to announce the beta release of Matter v0.9.0-beta.0! This release introduces powerful new features, significant performance improvements, and some breaking changes to pave the way for a smoother developer experience and a more robust system overall. We’ve also deprecated old functionality, giving you time to transition your code before these features are fully removed in future versions.

This beta release is designed for testing in real-world projects. Your feedback is critical to ensuring the stability and usability of these changes before the final release. Be sure to read the migration guide below for detailed instructions on updating your code.

---

What is a beta release?

Beta releases allow developers to try out new features and changes before they’re finalized. v0.9.0-beta.0 is a pre-release version, meaning it includes features, including breaking changes, for the next update but may still have bugs or edge cases that need refinement.

To use this beta release, you’ll need to explicitly specify the beta version in your project’s dependencies (e.g., Matter = "matter-ecs/matter@0.9.0-beta.0"). This ensures that your v0.8 and earlier projects don’t unintentionally pick up experimental changes.

Why use the beta?

• Access new features and performance improvements early.
• Help identify bugs or issues in your specific workflows.
• Influence the final version by providing feedback.

Your feedback directly shapes the quality of the final release. Please report any bugs or concerns you encounter while using the beta.

---

Highlights of this release

Added

• A new Loop:setWorlds({ World }) method which simplifies managing worlds in the Loop.
• A new deferred command mode for the registry which prevents iterator invalidation and optimizes command handling. This is now the default for Loop.
• Debugger enhancements:
  • Nested worlds within Loop are now fully supported.
  • Systems can be sorted by run time for better performance profiling.

Changed

• A breaking change: the Loop now requires a call to setWorlds before it can be used. The Debugger inherits this requirement.
• Significant Performance Improvements:
  • Queries now run 7.5-15x faster thanks to a reworked storage layout.
  • Archetypes are now more cache-friendly.
• System names in Loop are now cached, reducing overhead from debug.info.

Deprecated

• World:remove() return values no longer reliably indicate component removal status.
• World:optimizeQueries() has been deprecated as it no longer serves a purpose thanks to new storage changes.

Fixed

• Resolved an issue where archetypes were skipped in queries.
• Fixed World:queryChanged incorrectly omitting entities.

For more details, view the full changelog, or check out our documentation.

---

Migrating

Update your Loop initialization

Loop now requires a setWorlds({ World }) call before use. Update your setup code as follows:

Before:

local world = World.new()
local debugger = Debugger.new(Plasma)
local loop = Loop.new(world)

-- World is naively inferred from the loop parameter.

debugger:autoInitialize(loop)
loop:begin({
	default = RunService.Heartbeat,
})

After:

local world = World.new()
local debugger = Debugger.new(Plasma)
local loop = Loop.new(world)

-- World is explicitly set.
loop:setWorlds({ world })

debugger:autoInitialize(loop)
loop:begin({
	default = RunService.Heartbeat,
})

See the docs for more information.

Review deprecated methods

• Replace any reliance on the return value of World:remove().
  • If the return value is necessary you can call World:get() immediately before World:remove(), but keep in mind that this can still be misleading with command buffering (be sure to understand carefully how buffering affects what is currently in the world and what will change later).
• Potentially remove calls to World:optimizeQueries().
  • This can be done at a later time since it's now a no-op.

Prepare for deferred command mode

The registry now defaults to deferred command mode. This change is usually seamless but ensure your workflows don’t rely on immediate command execution.

The command buffering fundamentally changes how your actions interact with the underlying world data structure. This can result in different or unexpected behavior, particularly for edge cases involving entity lifecycle management, deferred commands, and query assumptions.

Why this change affects queries

The new deferred mode may:

• Change the order in which entities are returned by queries.
• Modify the visibility of entities in queries.
• Surface subtle bugs in query logic that relied on undocumented or implicit behaviors.

For example, queries that previously assumed a consistent order across iterations or relied on immediate execution of commands (e.g., insert, remove) may exhibit unexpected results.

Example: Deferred command mode batches modifications to entities and flushes them between systems. This means entities created or modified during a system may not appear in queries until the next system call.

Before:

world:insert(entity, ComponentA)
for entity in world:query(ComponentA) do
    print(entity) -- Entity with ComponentA appears immediately
end

After:

world:insert(entity, ComponentA)
for entity in world:query(ComponentA) do
    print(entity) -- The entity won't appear yet
end

Solution: Adjust your expectations or use deferred-safe workflows. For example, if immediate visibility is required, flush the command buffer explicitly with world:commitCommands(). Alternatively, move the behavior to a system that runs after your current system (this is preferred for new systems, but may be cumbersome for existing systems).

world:insert(entity, ComponentA)
world:commitCommands()
for entity in world:query(ComponentA) do
    print(entity) -- Entity with ComponentA appears immediately again
end

Tips for testing systems and queries

With the new storage layout, archetype improvements, and command buffering your queries may exhibit different performance characteristics. Test critical code paths to verify and maximize performance gains.

1. Validate Query Results: After updating, confirm that all queries return the expected results. Pay special attention to cases involving entity creation, deletion, or modification within the same frame.
2. Check Deferred Command Dependencies: If your systems depend on immediate execution, use world:commitCommands() to apply changes early, but sparingly, to maintain performance.
3. Profile Your Queries: Use the new runtime sorting feature in the Debugger to identify bottlenecks and ensure your queries are optimized for the new layout.
4. Iterate on Small Datasets: Start with a reduced set of entities and components to verify correctness before scaling up.
5. Handle Query Order Explicitly: Avoid assumptions about the natural order of query results. Use sorting or explicit filtering if order is critical.

---

How to provide feedback

Your input is invaluable to the final release of v0.9.0. Here’s how you can contribute:

1. Report Bugs: Submit issues with detailed reproduction steps.
2. Share Feedback: Tell us what you like and what could be improved.
3. Test Use Cases: Try integrating the beta into your projects and let us know about any pain points.
4. Get Involved: We welcome new contributors. Check our contribution guide or come talk to us.

Join the conversation in our GitHub issues or reach out through our discord server.

We can’t wait to hear your thoughts and see what you build with v0.9.0-beta.0!

Matter v0.8.4

Debugger improvements in Matter v0.8.4 are here!

This release focuses on several improvements to our debugger.

Added

• World variadic component validation thanks to methods that accept. Thanks to @Nidoxs in #100
  • At least one component must be provided in get, insert, replace, and remove
• Sorting for the world inspect table in the debugger. Thanks to @Nidoxs in #105
  • Clicking headers in the world inspect table will sort by that header
• You can now disable systems in the debugger by right clicking their entry in the system list. Thanks to @Nidoxs in #111
• Components now have syntax highlighting in the debugger. Thanks to @jackTabsCode in #98
  • This can be seen in the alt-hover tooltip and the entity inspector panel.
• A new query resource usage widget in the debuger. Thanks to @Nidoxs in #107
  • Displays each query's share of the system's total computation time

Changed

• The debugger alt-hover tooltip text is smaller and the background is slightly darker for improved legibility. Thanks to @Nidoxs in #96
• Replaced the debugger queries widget with the new query resource usage widget (mentioned above). Thanks to @Nidoxs in #107
  • This can be opened from the system inspect panel

Fixed

• The alt-hover tooltip now properly displays component data with each component being displayed on a new line. Thanks to @Nidoxs in #97
• The alt-hover tooltip no longer errors when the hovered entity is despawned. Thanks to @Nidoxs in #103
• Buttons no longer flash in the debugger's system inspect panel. Thanks to @Nidoxs in #114
  • Previously the "View queries" and "View logs" buttons would occasionally flash or flicker depending on factors such as framerate and resolution.
• Fix a bug in the documentation's replication guide example code. Thanks to @lolmanurfunny in #84

New Contributors

• @lolmanurfunny made their first contribution in #84
• @Nidoxs made their first contribution in #96
  • Huge thanks for numerous contributions in this release! ❤️

For more details, view the full changelog, or check out our documentation.

Matter v0.8.3

Fixed

• Iterating empty views properly iterates over nothing rather than the data structure members thanks to @memorycode in #81

For more details, view the full changelog, or check out our documentation.

Matter v0.8.2

Here is a small round of changes and fixes to things we've been updating recently.

Changed

• Optimize View performance. Thanks to @Ukendio in #73
• The code now uses Luau files due to better tooling support. Thanks to @Ukendio in #75

Fixed

• Reverted a regression in the debugger table format. Thanks to @jackTabsCode in #69
• Several fixes to noop queries.
  • snapshot properly returns an empty snapshot for noop queries. Thanks to @jackTabsCode in #68
  • view properly returns an empty view for noop queries. Thanks to @memorycode in #77
  • Calling noop queries is supported. Thanks to @MajestikButter in #72

New Contributors

• @memorycode made their first contribution in #66
• @MajestikButter made their first contribution in #72

For more details, view the full changelog, or check out our documentation.

Matter v0.8.1

This patch fixes a regression in our last release.

Fixed

• The archetype matching of QueryResult:without once again happens in the correct order according to cache invalidation thanks to @Ukendio in #63

For more details, view the full changelog, or check out our documentation.

Matter v0.8.0

This release contains several optimizations aimed at improving queries and fixes to the debugger and scheduler.

Updating

You can update to the latest version right away by using the wally scope and version matter-ecs/matter@0.8.0.

Many of the changes you see below will display better when using the latest version of Plasma. If you were already on v0.4 of Plasma and using the matter-ecs scope wally should be able to update to Plasma version 0.4.3 automatically. For those who are on the old package scope, or anyone else who would like to update, you can use the full wally scope and version matter-ecs/plasma@0.4.3 to see these latest improvements in their best light.

Added

• Added Views for random-accessing entities within queries. Thanks to @Ukendio in #31
  • Views are optimized for terse indexing, making them useful for traversing graphs of entities.
• Added Debugger.loopParameterNames which allows for labeling things passed to Loop. Thanks to @jackTabsCode in #58

Changed

• Disabled AutoLocalize on many Plasma Widgets. Thanks to @jackTabsCode in #55
  • This removes unnecessary computations for LocalizationService::attemptLocalization.
• Improved QueryResult:without to narrow archetype invariants. Thanks to @Ukendio in #4
  • The filter now works on the archetype-level rather than filtering entities
    ad-hoc which will immensely improve query performance.
• QueryResult:without now returns chainable methods. Thanks to @Ukendio in #18

Fixed

• Fixed the Scheduler not respecting priorities of systems. Thanks to @metrowaii in #51
• Fixed padding of items in the Debugger's state view. Thanks to @jackTabsCode in #54

New Contributors

• @ATK422 made their first contribution in #25

For more details, view the full changelog, or check out our documentation.

Matter v0.7.1

Matter v0.7.1 is here! 🎉

This release is primarily aimed at providing some small improvements and fixes since v0.7.0. We wanted to get things fixed up and in a place that feels good before continuing on to more drastic changes we have planned for the next major/minor release.

Updating

You can update to the latest version right away by using the wally scope and version matter-ecs/matter@0.7.1.

Many of the changes you see below will display better when using the latest version of Plasma. If you were already on v0.4 of Plasma and using the matter-ecs scope wally should be able to update to Plasma version 0.4.3 automatically. For those who are on the old package scope, or anyone else who would like to update, you can use the full wally scope and version matter-ecs/plasma@0.4.3 to see these latest improvements in their best light.

Changed

• Improved the usability of the world inspect widget. Thanks to @memorycode in 643e61b
• Optimized query unpacking. Thanks to @Ukendio in #27
• The debugger is more compact now. Thanks to @jackTabsCode in #32
• The debugger panel now better displays system ordering and performance. @jackTabsCode in #34
• The example game now uses an updated version of Plasma.

Fixed

• The slider widget in the debugger should now properly allow passing only a number rather than a table. Thanks to @Ukendio in 91a8482
• TestEZ is now a dev dependency rather than a regular dependency. Thanks to @Ukendio in 092fad8
• Fixed regressions in the loop scheduler. Thanks to @metrowaii in #1
  • Fixed the scheduler occasionally producing a non-deterministic ordering of systems.
  • Fixed the scheduler occasionally incorrectly detecting dependency cycles.

New Contributors

• @memorycode made their first contribution in 643e61b
• @metrowaii made their first contribution in #1
• @jackTabsCode made their first contribution in #32

For more details, view the full changelog, or check out our documentation.