var world = World.Create("My World");    // naming the world is optional
var entity = world.CreateEntity("my entity", 3, 5f);    
                                      // creates a new entity with components
                                      // components added this way will trigger
                                      // callbacks registered with world.OnSet()
                                      // setting the entity's string component
                                      // will change the entity's ToString() value

world.Destroy();  // when your done with a world, destroy it to free up it's resourcess
                  // This will automatically destroy all entities in that world

if(entity)              // returns false if entity is destroyed or invalid
{}                      // shorthand for entity.IsValid()

entity.Get<int>() += 4; // gets the entity's component by ref value.
                        // throws an exception if the entity is invalid or
                        // the entity does not have the component
                        // since they are returned by ref, you can assign values directly

entity.Set(3)             // sets the entity's components to values.
      .Set("my entity");  // can be chained to set multiple components at once.
                          // if entity does not already contain the component it will be added
                          // setting a component will trigger any callbacks registered
                          // with world.OnSet() 

if (entity.Has<int>())     // returns true if entity has component
{
  // do something
}

if (entity.TryGet(out int value)) // gets the component's value on entity, returns false if not found
{
    entity.Set(value + 4);        // Value types need to be set afterwards for changes to take place
}

entity.Remove<T>();   // removes the component on entity if found.
                      // if component was removed, will trigger any callbacks registered  with world.OnRemove()
                    
entity.Destroy();     // destroys the entity leaving it invalid
                      // all components on the entity will trigger their respective world.OnRemove() callbacks

var newWorld = World.Create("new World");
entity.Transfer(new_world);   // transfer moves entity to the specified world

entity.GetAllComponents(); // returns a copy of all the components assigned to the entity

entity.GetAllComponentTypes(); // returns a copy of all the component types assigned to the entity

// whenever an entity in the world sets an int, it'll invoke this callback
world.OnSet((ref int new_value) =>
    Console.WriteLine($"an entity set an int to {new_value}"));

// if you need the invoking entity, put it as the first parameter
world.OnSet((Entity entity, ref int new_value) => 
    Console.WriteLine($"{entity} set int to {new_value}"));

// if you need the previous value, simply put it between the entity
// and the new value without any modifiers.
// if the component did not have an old component, it'll be set to default
world.OnSet((Entity entity, int old_value, ref int new_value) => 
    Console.WriteLine($"{entity} set int {old_value} to {new_value}"));

// you can also name your callback
void IntSetCallback(ref int value)
{
    // do something
}

world.OnSet<int>(IntSetCallback); // then register it
world.OnSet<int>(IntSetCallback, false); // and later unregister by adding false as the second parameter

// the callback is invoked whenever an entity in the world with the component removes the component or is destroyed
world.OnRemove((int val) => 
    Console.WriteLine($"an entity removed int {val}"));

// put the entity as the first paramter to get the invoking entity
world.OnRemove((Entity e, int val) => 
    Console.WriteLine($"{e} removed int {val}");
    
// like OnSet, OnRemove can be named and registered and unregistered
void IntRemoveCallback(int value)
{
    // do something
}

world.OnRemove<int>(IntRemoveCallback);
world.OnRemove<int>(IntRemoveCallback, false);

var query = world.CreateQuery()                     // Queries operate on the world they are created with
                 .Has<int>()                        // your free to mix an match any filter overload
                 .Has(typeof(float), typeof(short)) // Has() filters entities to those with components
                 .Not<string>()                     // Not() filters for those that do not
                 .Not(typeof(ushort));              // there's no limit to the amount of filters you can add
                                                    // infact the more specific the better

query.Foreach( (ref int int_value, ref float float_value) =>  // you then use the foreach function to update your components
{                                                             // components must be prefaced with the ref modifier
    int_value ++;                                             // you can use up to 12 components as parameters
    float_value = int_value * 100;                            // queries operate only on entities that match both the query 
}));                                                          // filter and contains all the foreach parameters

query.Foreach( (Entity entity, ref int value ) =>         // you can access the current entity by putting it before the components
{                                                         // without modifiers. 
  Console.WriteLine($"{entity} value is {value}");        
});

var all_entities = world.CreateQuery();   // a simple way to match against all entities is to make a query with no filters

query.GetEntities();    // returns a copy of all entities currently matching the query

query.GetArchetypes();  // returns a copy of all archetypes currently matching the query

query.Clear();          // clears query filters, since the query has no filters it'll match against all entities

query.GetHasFilterTypes(); // returns all types in the Has() filter

query.GetNotFilterTypes(); // returns all types in the Not() filter

query.DestroyMatching();   // destroys all archtypes and their entities matching the query

var entity = world.Create("my entity", 3);
entity.Remove<string>();
entity.Has<string>();       // this will return false

query.Foreach((Entity entity, ref int int_val) =>
{
  entity.Remove<int>();     // since this is a structural change and we are in 
                            // the middle of iterating, this operation will be cached
  
  entity.Has<int>();        // since Remove() was cached, this will still return true
  
  entity.Set("my entity");  // set is regarded as a structural event so will 
                            // be cached regardless if the entity has the
                            // component or not
  
  entity.Has<string>();     // so this will still return false
});
// now all structural changes are applied since we are done iterating entities

entity.Has<string>();   // this will now return true
entity.Has<int>();      // and this will now return false

// you can manually iterate over a query using foreach
// however during manual iteration you should not do any structural changes
// as this many invalidate internal iterators
foreach(var archetype in query)
{
    if (archetype.TryGetEntityBuffer(out Entity[] entity_buffer) &&
        archetype.TryGetComponentBuffer(out int[] int_buffer))
    {
        for(int i = 0; i < archetype.EntityCount; ++ i) // use the entity count not buffer length
            System.Console.WriteLine($"{entity_buffer[i]} {int_buffer[i]}");
    }
}

if (!world.TryGetArchetype(out var archetype, typeof(int), typeof(float))) // gets an archetype with components
  return;                                                                  // returns false if world is invalid

var entity = world.Create(3);
var entity _archetype = entity.archetype;   // you can also get the archetype from valid entities
                                            // if entity is invalid, the archtype will also be invalid
                                            // an entity's archetype changes when the component types it
                                            // holds changes
  
if (archetype)  // use to check if archetype is valid
{               // valid entities will always have valid archetypes
  //...         // shorthand for archetype.IsValid()
}

var new_entity = archetype.CreateEntity();  // creates an entity using the archetype
                                            // the entity created will have all the components of the archetype set to default values
                                            // this is the most performant way to create entities
                                            // world.OnSet() is not invoked for the defaulted components

archetype.GetTypes();       // returns a copy of what components in the archetype
  
archetype.GetEntities();    // returns a copy of all entities in the archetype

archetype.ResizeBackingArrays(); // resizes the internal component and entity buffers to the minimum power of 2 needed to store them
                                 // may be useful if a large amount of entities were recently destroyed

if (archetype.TryGetEntityBuffer(out Entity[] entity_buffer))  // tries to get the raw entity storage buffer from
{                                                         // the archetype. Should be treated as readonly as
    for (int i = 0; i < archetype.EntityCount; ++ i)      // changing their values will break the ecs.
        Console.WriteLine(entity_buffer[i]);              // Valid indexes are only up to archetype.EntityCount
}                                                         // not entities.Length
                                                          // while iterating over raw buffers, structural changes should not be performed
                                                          // as this will possibly invalidate iterators

if (archetype.TryGetComponentBuffer(out int[] int_buffer))  // tries to get the raw component storage buffer
{                                                           // from the archetype. returns false if the archetype
    for(int i = 0; i < archetype.EntityCount; ++ i)         // is invalid or does not store the component
        int_buffer[i]++;                                    // entities in the entity buffer own the components in 
}                                                           // the component buffer that share the same index
                                                            // like the entity buffer, valid indexes are only up
                                                            // to archetype.EntityCount
                                                            
archetype.Destroy();    // destroys the archetype along with any entities it owns
                        // destroying the archetype is more efficient than destroying entities
                        // one by one

world.SetData(3)            // sets the world data to value
     .SetData("My Value");  // can be chained
     
world.GetData<float>() = delta_time;    // alternately you can use GetData
                                        // to get a reference and change it directly
                                        // throws an exception if the world is invalid
                                        // if data was not set before hand, get data will create and return defaulted data

query.Foreach((in float delta_time, Entity entity, ref Vector3 velocity) => 
{                                                     // you can access world data directly in queries using
    velocity += delta_time * new Vector3(1, 0, 0);    // the 'in' modifier before any entity
});                                                   // or component parameters
                                                      // you can add up to 4 world data in queries

world.GetAllWorldData(); // gets all WorldData created with SetData() or GetData()

world.GetAllWorldDataTypes(); // returns all the types of GetAllWorldData()

World.GetAll();                         // returns a copy of all the currently valid worlds

var world = World.Create("My World");   

var count = world.EntityCount;          // returns how many entities are in the world

world.GetEntities();                    // returns a copy of all the entities in the world

world.GetArchtypes();                   // returns a copy of all the archetypes in the world

world.ResizeBackingArrays();            // resizes all archetype backing arrays to the minimum power 
                                        // of 2 needed to store their data
                                        
world.DestroyEmptyArchetypes();         // destroys all archetypes that have no entities
                                        // this can potentially speed up queries since they no longer
                                        // have to iterate over those archetypes
                                        
world.CacheStructuralEvents(true);      // manually sets the world to cache structural events like when executing queries
                                        // set to false to apply all cached structural events
                                        
world.IsCachingStructuralEvents();      // returns true if the world is currently caching structural events