view release on metacpan or  search on metacpan

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

Within the callback, it is safe to add or delete entities, as well as to add
or remove components from those entities.

=head3 first

    my ( $guid, @comps ) = $view->first( sub ( $guid, @comps ) { ... } );
    my ( $guid, @comps ) = $view->first;

I<Since version 0.009, with no coderef since 0.102>

This function is similar to L<each|/each>, with the difference that iteration
through the view will stop early the first time the provided coderef returns a
true value. If no coderef is provided, the match will be the first element in
the view (it's equivalent to C<sub { 1 }>).

If the coderef ever returns true, a flat list with the GUID and the components
in the view will be returned. If it never returns true, this method will
return an empty list.

This function is equivalent to the following code

    my ( $guid, @comps )
        = map { ( $_[0], @{ $_[1] } ) }
        List::Util::first { $coderef->( $_[0], @{ $_[1] } ) } @{ $view };

=head3 entities

    @guids = $view->entities;

Returns a list of only the GUIDs of the entities in this view.

=head3 components

    @components = $view->components;

Returns a list of array references, each of which will hold the list of
components for a single entity in the view. The components will be in the
order provided when the view was created.

Useful for iterating like

    for ( $ECS->view(qw( A B C )) )->components ) {
        my ( $a, $b, $c ) = @$_;
        ...
    }

=head1 PERFORMANCE

Game::Entities aims to implement a simple entity registry that is as fast as
possible. Specifically, this means that it needs to be fast enough to be used
in game development, which is the natural use case for ECS designs.

To this end, the library caches component iterators which are invalidated
every time one of the components relevant to that iterator is either added
or removed from any entity. This should make the common case of systems
operating over sets of components that tend to be relatively stable
(eg. across game frames) as fast as possible.

The distribution includes two tests in its extended suite to test the
performance with iterations over large number of entities
(C<xt/short-loops.t>), and many iterations over small numbers of entities
(C<xt/long-loops.t>). Please refer to these files for accurate estimations.

=head1 SEE ALSO

=over

=item L<EnTT|https://skypjack.github.io/entt>

Much of the design and API of this distribution is based on that of the
entity registry in EnTT (famously used in Minecraft). A significant part
of the credit for the algorithms and data structures used by Game::Entities
falls on the EnTT developers and L<the blog posts|https://skypjack.github.io>
they've made to explain how they work.

=back

=head1 COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.