flame-engine/oxygen

A lightweight Entity Component System written in Dart.

Oxygen

A lightweight Entity Component System framework written in Dart.

About Oxygen

Oxygen is a lightweight Entity Component System framework written in Dart, with a focus on performance and ease of use. Oxygen is by design agnostic, and any game engine you want to use can be used with Oxygen.

Goals

Oxygen is heavily inspired by ECSY, and because of that it shares the same design principals. The main goal for Oxygen is to be lightweight, performant and simple to use. With APIs that try and help you make good use of the ECS design pattern, without restricting you in building your logic.

Documentation

See the documentation for more information about how to work with Oxygen.

Contributing

For contributing see our Contributing guidelines. Please read this carefully as it will answer most of your contributing-related questions.

Credits

• Inspired by ecsy

oxygen's Issues

HasNot<SomeComponent> filters don't work after SomeComponent is added to entities

Current bug behaviour

HasNot filters don't work on entities that have added components during runtime.

Expected behaviour

HasNot should filter out entities that have added the relevant component

Steps to reproduce

Create an entity and add CompoentA to it.
Create a Query with filters [Has<ComponentA>(), HasNot<ComponentB>()]
Add ComponentB to the entity and observe that the Query still has the entity in its entities list.

Analysis

The issue looks like it's due to the fact that entities are only added to systems when a component is added and removed from systems when a component is removed. But the complete opposite is true with HasNot filters, where an entity can be removed from a system when a component is added and an entity can be added to a system when a component is removed. The relevant code locations are here:

oxygen/lib/src/query/query_manager.dart

Lines 24 to 44 in e578c8e

	void _onComponentAddedToEntity(Entity entity, Type componentType) {
	for (final query in _queries.values) {
	// Entity should only be added when all the following conditions are met:
	// - the Entity matches the complete query.
	// - the Entity is not already part of the query.
	if (query.match(entity) && !query._entities.contains(entity)) {
	query._entities.add(entity);
	}
	}
	}
	void _onComponentRemovedFromEntity(Entity entity, Type componentType) {
	for (final query in _queries.values) {
	// Entity should only be removed when all the following conditions are met:
	// - the Entity matches the complete query.
	// - the Entity is not already part of the query.
	if (!query.match(entity) && query._entities.contains(entity)) {
	query._entities.remove(entity);
	}
	}
	}

Null safety by default?

Hey, I see that the development just has been started and I like the idea behind the project. It looks like the project won't be GA immediately. Thus, it looks like a good idea to make it null safe from the start.

What do you think about that?

Components cant be removed but can be marked for removal?

Current bug behaviour

If I add a component and then remove it, it does not get removed.

Expected behaviour

A component marked for removal would be removed.

Steps to reproduce

---

import 'package:oxygen/oxygen.dart';
import 'package:test/test.dart';

class TestComponent extends ValueComponent<void> {}

class ComponentAdderSystem extends System {
  late Query query;
  @override
  void init() {
    query = createQuery([HasNot<TestComponent>()]);
  }

  @override
  void execute(double delta) {
    for (final entity in query.entities) {
      entity.add<TestComponent, void>();
    }
  }
}

class ComponentRemoverSystem extends System {
  late Query query;
  @override
  void init() {
    query = createQuery([Has<TestComponent>()]);
  }

  @override
  void execute(double delta) {
    for (final entity in query.entities) {
      entity.remove<TestComponent>();
    }
  }
}

void main() {
  group('Component', () {
    test('Components should be added and removed from entities.', () {
      final world = World();
      world.registerComponent<TestComponent, void>(() => TestComponent());
      world.registerSystem(ComponentRemoverSystem());
      world.registerSystem(ComponentAdderSystem());
      var testEntity = world.createEntity('Test Entity');
      world.init();

      expect(false, testEntity.has<TestComponent>(),
          reason: 'Entity has component it shouldnt.');
      world.execute(1);
      testEntity = world.entities.first;
      expect(true, testEntity.has<TestComponent>(),
          reason: 'Entity does not have required component.');
      world.execute(1);
      testEntity = world.entities.first;
      expect(false, testEntity.has<TestComponent>(),
          reason: 'Entity has component it shouldnt.');
    });
  });
}

---

More environment information

• Oxygen version: 0.2.0

More information

I created a fork where I made the changes that I thought would be needed here:

https://github.com/billHaggerty/oxygen/blob/main/lib/src/world.dart#L66
https://github.com/billHaggerty/oxygen/blob/main/lib/src/entity/entity_manager.dart#L157
https://github.com/billHaggerty/oxygen/blob/main/lib/src/entity/entity_manager.dart#L165
https://github.com/billHaggerty/oxygen/blob/main/lib/src/entity/entity_manager.dart#L112

This all seems like it was supposed to work. The components to be removed were being tracked but I couldn't see what was supposed to actually remove them. If I was missing something please let me know.

Create v0.3 and include bugs fixes in flame_oxygen

A couple of bugs were fixed a few months ago but no new release was created. v0.2 dates from before the bugs fix PR. That PR fixes the bug with removing components from entities, which is very important (it's a blocker for any game not to have it).

To use it, we need to do following:

dependency_overrides:
  oxygen:
    git:
      url: https://github.com/flame-engine/oxygen.git

And, additionally, we also need to amend FlameWorld by adding entityManager.processRemovedComponents(); to its update method.

It would be super useful if you could create a new release for oxygen, and then do the quick change to flame_oxygen.

Example do not work

Current bug behavior

Run the example as described in Readme.md:
dart --enable-asserts lib/main.dart
and see the output:

Error: Couldn't resolve the package 'example' in 'package:example/components/color_component.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/components/direction_component.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/components/name_component.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/components/player_component.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/components/velocity_component.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/systems/player_move_system.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/utils/color.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/utils/game.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/utils/vector2.dart'.
Error: Couldn't resolve the package 'example' in 'package:example/utils/terminal.dart'.

Expected behaviour

The example works without errors.

Steps to reproduce

cd example
dart --enable-asserts lib/main.dart