view release on metacpan or  search on metacpan

lib/Game/Entities.pod  view on Meta::CPAN

this method will silently overwrite it.

Multiple components can be specified, and they will all be added in the order
they were provided.

Starting from version 0.101 this method returns the invokant, so it supports
chaining.

=head2 get

    $component  = $ECS->get( $guid, $component_name );
    @components = $ECS->get( $guid, @component_names );

Takes an entity's GUID and the name of a component as a string, and retrieves
the component with that name for the specified entity, if it exists. If the
entity has no component by that name, this method returns undefined instead.

Multiple components names can be specified, and they will all be retrieved and
returned in the order they were provided.

When called with a single target component name, this method returns a scalar.
When called with a list of components names, it will return a list.

=head2 delete

    $ECS = $ECS->delete( $guid );
    $ECS = $ECS->delete( $guid, @component_names );

When called with only an entity's GUID, it deletes all components from the
entity, and marks that entity's GUID as invalid.

When called with one or more additional component names,the components by
those names will be removed from the specified entity in the order provided.
Deleting a component from an entity is an idempotent process.

Starting from version 0.101 this method returns the invokant, so it supports
chaining.

=head2 check

    $bool = $ECS->check( $guid => $component_name );

Takes an entity's GUID and a component name and returns a truthy value if the
specified entity has a component by that name, or a falsy value otherwise.

=head2 valid

    $bool = $ECS->valid($guid);

Takes an entity's GUID and returns a truthy value if the specified entity is
valid, or a falsy value otherwise. An entity is valid if it has been created
and not yet deleted.

=head2 created

    $count = $ECS->created;

Returns the number of entities that have been created. Calling L<clear|/clear>
resets this number.

=head2 alive

    $count = $ECS->alive;

Returns the number of created entities that are still valid. That is:
entities that have been created and not yet deleted.

=head2 clear

    $ECS = $ECS->clear;

Resets the internal storage of the registry. Calling this method leaves no
trace from the previous state.

Starting from version 0.101 this method returns the invokant, so it supports
chaining.

=head2 sort

    $ECS = $ECS->sort( $component_name => $parent_name );
    $ECS = $ECS->sort( $component_name => sub { $a ... $b } );
    $ECS = $ECS->sort( $component_name => sub ($$) { $_[0] ... $_[1] } );

I<Since version 0.006, with support for prototypes since 0.011>

Under normal circumstances, the order in which a particular set of components
is stored is not guaranteed, and will depend entirely on the additions and
deletions of that component type.

However, it will sometimes be useful to impose an order on a component set.
This will be the case for example when renderable components need to be drawn
back to front, etc.

This function accommodates this use case.

Given a single component name, and a code reference to a comparator function,
the specified component will be sorted accordingly. The comparator function
behaves just like the one used for the regular
L<sort|https://perldoc.perl.org/functions/sort>, accessing the two components
being compared via the C<$a> and C<$b> variables, or as the first two values
in C<@_> if the comparator has the a prototype equal to C<$$>.

Alternatively, if given the name of another component (C<B>) instead of a
comparator function, the order of the first component (C<A>) will follow that
of the C<B>. After this, iterating over the entities that have C<A> will
return

=over

=item * all of the entities that also have C<B>, according to the order in C<B>

=item * all of the entities that I<do not> have C<B>, in no particular order

=back

Sorting a component pool invalidates any cached views that use that component.

The imposed order for this component is guaranteed to be stable as long as no
components of this type are added or removed.

Starting from version 0.101 this method returns the invokant, so it supports
chaining.