echoes

KO | EN

gitlite — search

#javascript #python #ai #typescript #go #android #docker #nodejs #java #windows #awesome #awesome-list #pytorch #mcp

(★ 46)

A macro-based Entity Component System framework, focusing on ease of use.

echoes 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Echoes
A macro-based [Entity Component System](https://en.wikipedia.org/wiki/Entity_component_system) framework, focusing on ease of use.

This framework was [designed and implemented by deepcake](https://github.com/deepcake/echo), and is now maintained by player-03.

## Overview

- A component is an individual piece of data. It can be a string, a class, an abstract, or any other type.
- An [entity](src/echoes/Entity.hx) is a collection of components. It fills a similar role to object instances in object-oriented programming, but functions differently. Its components aren't pre-defined the way an object's variables are; in fact, you can mix and match them at runtime.
  - Usage: Create an entity with `entity = new echoes.Entity()`. Next, call `entity.add(new Component())` for each component you want to add.
- A [system](src/echoes/System.hx) updates and modifies entities. Whereas in object-oriented programming, objects usually have instance methods to update themselves, here that job is reserved for systems.
  - Systems use [views](src/echoes/View.hx) to filter entities. `View<A, B>` lists all entities with both the `A` component and the `B` component, which is convenient when a system wants to modify that specific data.
  - Usage: Create a class that extends `echoes.System`, and write functions that take components as arguments. Echoes will automatically find entities with those components, allowing you to modify the data.
    - To make a new system run, either call `system.activate()` or add it to an already-active `SystemList`.
    - See [usage](#usage) for details.
- The [`Echoes` class](src/echoes/Echoes.hx) tracks all active entities and systems.
  - Usage: Call `Echoes.init()` when the app loads, or manually call `Echoes.update()` once per frame.

## Usage

To install Echoes, run `haxelib install echoes` or `haxelib git https://github.com/player-03/echoes.git`.

### One system

In this example, we create a single system and use it to manage a single entity. This system's only job is to render an entity's `DisplayObject` at that entity's `Position`. For now, we'll hard-code those two components.

```haxe
import echoes.Entity;
import echoes.System;
import echoes.Echoes;

class EchoesExample {
	public static function main():Void {
		Echoes.init();
		
		//Create and activate an instance of our system.
		new RenderSystem(createScene()).activate(); //Details below.
		
		//Create an entity with the components our system will use. Entities are
		//activated automatically unless `false` is passed.
		var appleTree:Entity = new Entity();
		appleTree.add(loadImage("assets/AppleTree.png"));
		appleTree.add(new Position(100, 0));
		//...
	}
	
	private static function createScene():Scene {
		//Details omitted for brevity.
	}
	
	private static function loadImage(path:String):DisplayObject {
		//Details omitted for brevity.
	}
}

class RenderSystem extends System {
	public final scene:Scene;
	
	public function new(scene:Scene) {
		super();
		
		this.scene = scene;
	}
	
	/**
	 * This function is called whenever any entity gains a `DisplayObject`
	 * component, and it adds the `DisplayObject` to the scene.
	 */
	@:add private function onDisplayObjectAdded(displayObject:DisplayObject):Void {
		scene.addChild(displayObject);
	}
	
	/**
	 * This function is called whenever any entity loses a `DisplayObject`
	 * component, and it removes the `DisplayObject` from the scene.
	 */
	@:remove private function onDisplayObjectRemoved(displayObject:DisplayObject):Void {
		scene.removeChild(displayObject);
	}
	
	/**
	 * This function is called several times per frame, once for every entity
	 * with **both** a `DisplayObject` and a `Position`. It keeps the two
	 * components in sync, moving the former to match the latter.
	 */
	@:update private function updatePosition(displayObject:DisplayObject, position:Position):Void {
		displayObject.x = position.x;
		displayObject.y = position.y;
	}
	
	/**
	 * This function is called once per frame, after all calls to
	 * `updatePosition()` have returned. If you need to clean anything up at the
	 * end of a frame, this is a good place to do it.
	 */
	@:update private function finalize():Void {
		//...
	}
}
```

### Two systems

This example adds a second system that move entities around.

```haxe
import echoes.Entity;
import echoes.System;
import echoes.SystemList;
import echoes.Echoes;

class EchoesExample {
	public static function main():Void {
		Echoes.init();
		
		//Use a `SystemList` to group related systems.
		var physicsSystems:SystemList = new SystemList("Physics");
		physicsSystems.add(new MovementSystem()); //Details below.
		physicsSystems.add(new CollisionSystem()); //Not shown.
		
		//Adding `physicsSystems` first means that entire group will run before
		//`RenderSystem`, even if more systems are added later.
		physicsSystems.activate();
		new RenderSystem().activate(); //Details in previous example.
		
		//Create entities: one tree and two rabbits. The rabbits will race
		//towards the tree.
		var appleTree:Entity = new Entity();
		appleTree.add(loadImage("assets/AppleTree.png"));
		appleTree.add(new Position(100, 0));
		
		//`add()` returns the entity, allowing you to chain calls.
		var john:Entity = new Entity()
			.add(new Position(0, 0))
			.add(new Velocity(2.5, 0))
			.add(loadImage("assets/Rabbit.png"))
			.add(("John":Name));
		
		//`add()` can also take multiple components.
		var jack:Entity = new Entity();
		jack.add(new Position(150, 0), new Velocity(-2.5, 0));
		jack.add(loadImage("assets/Rabbit.png"), ("Jack":Name));
		
		//You can manually access and modify components.
		john.get(Velocity).x = 4.5;
		trace(john.get(Velocity)); //{ x: 4.5, y: 0 }
		
		trace(jack.get(Position).x); //150
		trace(jack.get(Name)); //"Jack"
	}
	
	private static function loadImage(path:String):DisplayObject {
		//[Details omitted for brevity.]
	}
}

//[RenderSystem omitted for brevity.]

//[Position and Velocity omitted for brevity.]

//Using typedefs allows you to assign meaning to common types. `Name` is now its
//own component type, distinct from `String`. An entity will be able to have
//both a `Name` and a `String` component, or one without the other.
typedef Name = String;

class MovementSystem extends System {
	private var timeElapsed:Float = 0;
	
	/**
	 * This function is called several times per frame, once for every entity
	 * with **both** a `Position` and a `Velocity`.
	 * 
	 * `Float` is a special case, and is never treated as a component.
	 */
	@:update private function updatePosition(position:Position, velocity:Velocity, time:Float):Void {
		//Changing the entity's position a small amount each frame produces the
		//appearance of smooth motion. Later on, `RenderSystem` will update each
		//entity's `DisplayObject` to match this position.
		position.x += velocity.x * time;
		position.y += velocity.y * time;
	}
	
	/**
	 * This `View` object lists every entity with a `Velocity`. Because the
	 * `View` constructor is private, you must call `getLinkedView()` instead.
	 */
	private var velocityView:View<Velocity> = getLinkedView(Velocity);
	
	/**
	 * Because `Float` is a special case, this function behaves like
	 * `RenderSystem.finalize()`, being called only once per update.
	 */
	@:update private function countTime(time:Float):Void {
		if(timeElapsed >= 20) {
			return;
		}
		
		timeElapsed += time;
		
		if(timeElapsed >= 20) {
			trace("Race over!");
			
			//Iterate through all entities with `Velocity` components, and make
			//them all stop moving.
			for(entity in velocityView.entities) {
				var velocity:Velocity = entity.get(Velocity);
				velocity.x = 0;
				velocity.y = 0;
			}
		}
	}
}
```

### Special arguments
Certain argument types have special meanings, for easy access to information. `Float` refers to the duration of this update, in seconds, and `Entity` refers to the entity being processed.

When you take an argument of either type, instead of getting a component as normal, you get the special value. Plus, the function will be called even though the entity doesn't have corresponding components. (In fact, entities aren't allowed to have those components.)

```haxe
//The entity must have `Position` and `Velocity`, but `Float` will be provided.
@:update private function updatePosition(position:Position, velocity:Velocity, time:Float):Void {
	position.x += velocity.x * time;
	position.y += velocity.y * time;
}

//Taking an `Entity` argument allows you to view and modify components.
@:update private function stopIfOutOfBounds(position:Position, entity:Entity):Void {
	//entity.get() is just a little more verbose, but does the same thing.
	if(position != entity.get(Position)) {
		throw "Those should always be equal.";
	}
	
	//You can create code that only runs when an optional component exists.
	if(entity.exists(Velocity) && Math.abs(position.x) > 200) {
		entity.remove(Velocity);
	}
}
```

Echoes also supports the standard "optional argument" syntax.

```haxe
//Only `Position` is required, but `Velocity` will be provided if available.
@:update private function stopAtBounds(position:Position, ?velocity:Velocity):Void {
	if(position.x > 200) {
		position.x = 200;
		
		if(velocity != null) {
			velocity.x = 0;
		}
	} else if(position.x < -200) {
		position.x = -200;
		
		if(velocity != null) {
			velocity.x = 0;
		}
	}
}
```

## Advanced

### Type check syntax
Due to how Haxe parses code, components with type parameters don't work normally, and special syntax is required.

For instance, `entity.add(["my", "string", "array"]))` adds a string array to an entity, but `entity.remove(Array<String>)` won't compile. In this context, Haxe interprets `Array<String>` as "`Array` is less than `String` is greater than (nothing)", and it complains that it expected a value after `>`.

To get around this, Echoes accepts [type check syntax](https://haxe.org/manual/expression-type-check.html) anywhere it accepts a `Class<T>`. The left side of the expression will be ignored, so you can use an identifier that doesn't exist, like `_`. Because this alerts Haxe to expect a type, it will successfully parse anything entered on the right side.

For instance, to remove the string array from the above example, call `entity.remove((_:Array<String>))`.

### Update order

To make an app run smoothly, you often need to run updates in a specific order. For simple apps, all you need to do is call `activate()` in the correct order and pay attention to the order of each system's `@:update` functions. The systems will run in the order you added them, and within each system, the `@:update` functions will run from top to bottom.

```haxe
class Main {
	public static function main():Void {
		Echoes.init();
		
		new FirstSystem().activate();
		new SecondSystem().activate();
	}
}

class FirstSystem extends System {
	@:update private function first():Void {
		trace(1);
	}
	@:update private function second():Void {
		trace(2);
	}
}

class SecondSystem extends System {
	@:update private function first():Void {
		trace(3);
	}
	@:update private function second():Void {
		trace(4);
	}
}
```

#### SystemList

[`SystemList`](src/echoes/SystemList.hx) is a system that tracks a list of other systems. During an update, it runs all of its systems in a row before returning.

```haxe
class Main {
	public static function main():Void {
		Echoes.init();
		
		var enterFrame:SystemList = new SystemList();
		var midFrame:SystemList = new SystemList();
		var exitFrame:SystemList = new SystemList();
		
		//Run all `enterFrame` systems first, then all `midFrame` systems, then
		//all `exitFrame` systems.
		enterFrame.activate();
		midFrame.activate();
		exitFrame.activate();
		
		//Even if `exitFrame` systems are defined first, they'll run last.
		exitFrame.add(new ExitFrameSystem());
		exitFrame.add(new ExitFrameSystem2());
		
		//Even if `enterFrame` systems are defined second, they'll run first.
		enterFrame.add(new EnterFrameSystem());
		enterFrame.add(new EnterFrameSystem2());
		
		//Even if `midFrame` systems are defined last, they'll run in between
		//`enterFrame` and `exitFrame`.
		midFrame.add(new MidFrameSystem());
		midFrame.add(new MidFrameSystem2());
	}
}
```

Because `SystemList` is itself a system, you can nest lists for finer control.

```haxe
class Main {
	public static function main():Void {
		Echoes.init();
		
		var enterFrame:SystemList = new SystemList();
		enterFrame.add(new EnterFrameSystem());
		enterFrame.add(new EnterFrameSystem2());
		enterFrame.activate();
		
		var midFrame:SystemList = new SystemList();
		midFrame.add(new MidFrameSystem());
		midFrame.activate();
		
		//Set up `physics` as part of `midFrame`.
		var physics:SystemList = new SystemList();
		physics.add(new GravitySystem());
		physics.add(new MomentumSystem());
		midFrame.add(physics);
		
		//Any later additions to `midFrame` will run after `physics`.
		midFrame.add(new MidFrameSystem2());
		
		//Any later additions to `physics` will still run during `physics`,
		//which means after `MidFrameSystem` and before `MidFrameSystem2`.
		physics.add(new CollisionSystem());
		
		var exitFrame:SystemList = new SystemList();
		exitFrame.add(new ExitFrameSystem());
		exitFrame.add(new ExitFrameSystem2());
		exitFrame.activate();
	}
}
```

Also note that each `SystemList` has its own `paused` property, which prevents `@:update` events for any system in that list. So in the above example, you could pause `physics` without pausing anything else. Or you could pause `midFrame` (which implicitly pauses `physics`) while allowing `enterFrame` and `exitFrame` to keep going.

#### Priority

The `@:priority` metadata is another way to control update order. Raising a system's priority makes it run before lower-priority systems, and lowering its priority makes it run after. Within a priority bracket, systems run in the order they were added, as usual.

```haxe
//The default priority is 0.
class AverageSystem extends System {
	//...
}

//The `@:priority` metadata sets a system's priority.
@:priority(1)
class HighPrioritySystem extends System {
	//...
}

class Main {
	public static function main():Void {
		Echoes.init();
		
		//Priority 1 > priority 0, so `HighPrioritySystem` will run first
		//despite being added second.
		new AverageSystem().activate();
		new HighPrioritySystem().activate();
		
		//Alternatively, the default system constructor allows setting priority
		//on a case-by-case basis. Priority -1 is the lowest of the three, so
		//this will run last.
		new HighPrioritySystem(-1).activate();
	}
}
```

Individual `@:update` listeners can have their own priorities. These listeners will run at a different time than the rest of the system.

```haxe
@:priority(1)
class MultiPrioritySystem extends System {
	//Any listener without a `@:priority` tag will run at the system's priority.
	//Like the system itself, `first()` will run near the start of an update.
	@:update private function first(data:Data):Void {
		//Begin collecting data.
		data.collectData = true;
	}
	
	//A listener with negative priority will run near the end of the update.
	//Currently, there's no option to override this priority at runtime.
	@:update @:priority(-1) private function last(data:Data):Void {
		//Now that the default priority systems are done, analyze their data.
		data.analyze();
		
		//Don't collect data between updates.
		data.collectData = false;
	}
}
```

If using multiple `SystemList`s, be aware that priority only affects a system's position within its `parent` list. No matter how high or low the priority, the system can't run any earlier than the start of its `parent`, or any later than the end.

```haxe
class Main {
	public static function main():Void {
		Echoes.init();
		
		var list:SystemList = new SystemList();
		
		//Because `AverageSystem` and `list` both have priority 0, they run in
		//the order they're added.
		new AverageSystem().activate();
		list.activate();
		
		//No matter how high a system's priority, if it's added to `list` it
		//will run during `list`, and will come after `AverageSystem`.
		list.add(new HighPrioritySystem());
		
		//You can modify any system or system list's priority after the fact.
		//This will cause `list` (including `HighPrioritySystem`) to run first.
		list.priority = 1;
	}
}
```

The argument to `@:priority` can be any integer expression. For instance, `@:priority(OtherSystem.DEFAULT_PRIORITY + 1)` will make the listener run before `OtherSystem`. The expression will be evaluated during the constructor, meaning it can access the constructor's `priority` argument.

### Update length

As Glenn Fielder explains in his article ["Fix Your Timestep!"](https://www.gafferongames.com/post/fix_your_timestep/), games and physics simulations can be very sensitive to the length of each update. `@:update` listeners in Echoes are no exception.

Fix Your Timestep! lists a number of situations you may want to account for, and a couple different approaches. Fortunately, Echoes natively supports all of these solutions.

By default, `Echoes.update()` uses the "semi-fixed timestep" approach. It calculates how much time has passed since the last update, applies a maximum length of one second, and calls each `@:update` listener with that timestep.

If one second is too long, or if you want a fixed timestep, all you need to do is customize `Echoes.clock`. `Echoes.clock.maxTime` controls the maximum length of an update, and `Echoes.clock.setFixedTimestep()` divides each update into a number of fixed timesteps. (Any remaining time after an update will be carried over to the next update.)

In order to ["free the physics,"](https://www.gafferongames.com/post/fix_your_timestep/#free-the-physics) you may want to run physics-related systems at a different rate than everything else. Fortunately, each [`SystemList`](src/echoes/SystemList.hx) ([described above](#systemlist)) has its own [`Clock`](src/echoes/utils/Clock.hx). If you have a `SystemList` for physics systems, you can call `physicsSystemList.clock.setFixedTimestep()` without affecting any of the other systems.

### Replacing components

Normally, calling `Entity.add()` will always dispatch an `@:add` listener. If there was an old value of that type, it will be replaced, but no `@:remove` event will be dispatched for it.

```haxe
final entity:Entity = new Entity();
entity.add(new DisplayObject("One.jpg")); //Dispatches `@:add`
entity.add(new DisplayObject("Two.jpg")); //Dispatches `@:add`
```

If cleanup is necessary (for instance, image data might need to be freed), this would normally happen in a `@:remove` listener. To force Echoes to dispatch this event, tag the component type `@:echoes_replace`.

```haxe
@:echoes_replace
class DisplayObject {
	public function new(filePath:String) {
		//...
	}
	
	public function free():Void {
		//...
	}
}
```

This tag changes the behavior of `Entity.add()`. Normally, it would call `ComponentStorage.add()`, but for components tagged `@:echoes_replace`, it calls `ComponentStorage.replace()` instead. This will cause it to dispatch a `@:remove` event followed by an `@:add` event.

Importantly, `ComponentStorage.replace()` sets the new value before dispatching either event. This means that the `@:remove` listener has access to both the old value and the new value, and can tell that a replacement is happening.

```haxe
class ImageSystem extends System {
	@:remove private function freeDisplayObject(object:DisplayObject, entity:Entity):Void {
		//The old value is passed to the function as the `object` argument. It's
		//been removed, and should be freed.
		object.free();
		
		//`entity` will have the new value, if any.
		if(entity.exists(DisplayObject)) {
			final newDisplayObject:DisplayObject = entity.get(DisplayObject);
			//`newDisplayObject` is the new value, and can be used here. Also,
			//`ComponentStorage.replace()` will dispatch an `@:add` event for it
			//before returning, which may be a better time to handle it.
		} else {
			//There's no replacement; perform additional cleanup as appropriate.
		}
	}
}
```

### Compiler flags
Echoes offers a few ways to customize compilation.

- `-Dechoes_profiling` turns on time tracking. With this flag enabled, `Echoes.getStatistics()` will include the amount of time spent on each system during the most recent update.
- `-Dechoes_report` prints a list of all compiled components and views.
- `-Dechoes_max_name_length=[number]` adjusts the length of generated class names, which can help if you exceed your operating system's filename length limit.

## Breaking changes

### Since v1.1.0

- `@:add` events are no longer dispatched while an entity is being deactivated. This would only happen if a `@:remove` listener added a component, and if one does, the event can wait until the entity is reactivated.

### Since v1.0.0

- Creating a view with two of the same component is now an error.
- The built-in entity templates are deprecated. Instead, please use the separate [Echoes templates](https://github.com/player-03/echoes-templates) library.

### Since v1.0.0-rc.5

- `Echoes.addSystem()`, `Echoes.hasSystem()`, and `Echoes.removeSystem()` have been replaced by `system.activate()`, `system.active`, and `system.deactivate()`, respectively.
- `Entity.getComponents()` now returns a list of `ComponentStorage` instances, instead of a map. If you prefer the old format, you can perform an implicit cast: `var map:Map<String, Dynamic> = Entity.getComponents()`.
- Systems no longer receive `@:remove` events when deactivated.
- `View.entities` is now an `Array` rather than a `List`. You can still iterate over it as before, but you'll have to call `contains()` rather than `has()` if you want to check existence.
- `Echoes.activeEntities` and `View.entities` may be re-ordered when entities or their components are removed. You can set `-D echoes_stable_order` to preserve the order, potentially at the cost of speed.
- `@:remove` listeners are no longer allowed to add back the component that's currently being removed. They may still add other components as normal.
- `SystemList.exists()` now searches recursively, returning true for grandchildren as well as direct children.

### Since v1.0.0-rc.3

- Macro users only: `ComponentStorageBuilder.getComponentStorage()` now returns the full `StorageType.instance` expression, not just a value that can be parsed to find `StorageType`. If you need the old value, use `getComponentStorageName()`. None of this affects `Echoes.getComponentStorage()`, which continues to work as before.
- Entity templates may no longer define their own constructor, and should instead declare an `onApplyTemplate()` function that takes no arguments.
- In an entity template, you must now use variables (not properties) to declare components. Properties now have their default Haxe behavior.

### Since v1.0.0-rc.2

- `Echoes.getSingleton()` is now `Echoes.getView()`, `Echoes.getInactiveView()`, and `Echoes.getComponentStorage()`, all of which take arguments instead of using `getExpectedType()`.
- `System.makeLinkedView()` is now `System.getLinkedView()`, which takes arguments instead of using `getExpectedType()`.

### Since deepcake/echo

Entities:

- `Entity.print()` is now `Entity.getComponents()`. This returns a `Map`, allowing you to iterate over all of the components.
- The `isActive()`, `isDestroyed()` and `status()` functions have been condensed into the `active` and `destroyed` properties.
- When you call `entity.add()`, Echoes will dispatch an `@:add` event whether or not a component of that type already existed. (Previously, it would only do so if it didn't exist.)
- You can no longer automatically convert `Entity` to or from `Int`. Instead, use `entity.id`.

Components:

- Typedefs are treated as their own components, distinct from the underlying type. To disable this behavior, mark the typedef `@:eager`.
- `Storage` and `ICleanableComponentContainer` have been merged into `ComponentStorage`.
- Components may no longer be `null`. Trying to add a null component instead removes that component (if it exists).

Systems:

- Systems no longer initialize `View` variables automatically. You must now call `getLinkedView()` for the same behavior.
- `@rm` is no longer a valid way to shorten `@:remove`. You may now omit any number of letters from the end, but not from the middle. (Thus, `@:rem` is now valid.)
- As far as listener functions are concerned, `Int` no longer means anything special. To get a reference to the entity, take an argument of type `Entity`.

Miscellaneous:

- Haxe 3 is no longer supported.
- `Echoes.update()` will calculate the elapsed time on its own, and no longer takes an argument. If you need to adjust the rate at which time passes, adjust `Echoes.activeSystems.clock`.
- `-Dechoes_array_container` and `-Dechoes_vector_container` have been removed.
- `Echoes.info()` is now `Echoes.getStatistics()`.

Finally, several classes and variables were renamed. Use these find-and-replace operations to update your code.

Find | Replace with | Notes
---- | ------------ | -----
`echoes.core` | `echoes`
`Workflow` | `Echoes`
`Echoes.entities` | `Echoes.activeEntities`
`Echoes.views` | `Echoes.activeViews`
`Echoes.systems` | `Echoes.activeSystems`
`Echoes.addSystem(system)` | `system.activate()` | You might have used a different variable name than `system`.
`Echoes.removeSystem(system)` | `system.deactivate()` | Ditto.
`AbstractView` | `ViewBase` | Import `echoes.View`.
`ISystem` | `System` | Change "`implements`" to "`extends`," if applicable.
`ICleanableComponentContainer` | `ComponentStorage`
`view.size()` | `view.entities.length` | You might have used a different variable name than `view`.
`view.isActive()` | `view.active` | Ditto.
`onAdded.add()` | `onAdded.push()`
`onAdded.size()` | `onAdded.length`
`onRemoved.add()` | `onRemoved.push()`
`onRemoved.size()` | `onRemoved.length`

echoes

echoes 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

echoes

echoes 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README