feature: creature (#38)

* build(deps): add assimp library as dependency

* feat(render): add model loading and rendering pipeline

* refactor(render): rename depth player shaders to depth model and clean up

* build: add EnTT library

* feat(entity): add ECS-based entity rendering

* feat(render): add shadow pass for entity models

* refactor(render): unify model and player rendering with single shader pipeline

* refactor(collision): convert AABB to center-half representation and migrate player data to ECS

* refactor(gameplay): add base classes Chunk and World for shared logic

* feat(gameplay): implement entity movement system with collision detection

- Add Velocity and HitBoxes components to entity
- Introduce HitboxManager for loading per-entity collision AABBs from JSON
- Create MoveSystem with per-axis collision handling
- Move get_block_aabb to base World class and add virtual get_per_tick_time
- Remove static get_block_aabb from ClientWorld; use member m_per_tick_time for tick duration

* fix(gameplay): correct hitbox insertion in HitboxManager::load

* build: remove entt library

* refactor(gameplay): replace entt components with SparseVector for player data

Refactor client world to use a custom SparseVector for player data instead of entt registry. Consolidate Transform, ViewAngles, and related structs into Position, Orientation, WalkPose. Introduce PlayerData and PlayerRenderData. Remove the unused move_system.cpp. Unify player render and shadow render into a single function.

* feat(render): add model ID system with concurrent lookup and namespace-based loading

- Extract `ModelID` and `Model` struct to new `model.hpp`
- Replace `std::unordered_map` with `tbb::concurrent_hash_map` for thread safety
- Add `get_model(ModelID)`, `get_model_id`, `get_model_name` methods
- Parse model names in `namespace:name` format to construct asset paths
- Update `load_model` to accept `string_view` and use ID-based management

* refactor(gameplay): extract movement, gravity, orientation, and walk pose into structs

* refactor(gameplay): extract Entity base class from ClientPlayer

Move position, walk pose, velocity, orientation, movement, and gravity
fields and their accessors into a new Entity base class. ClientPlayer now
inherits from Entity, removing duplicated members. Also update velocity
handling to use 3D vector per axis and adjust related logic.

* feat(player): split max speed into horizontal/vertical, set spawn pos

* refactor: move movement logic into SpeedSystem and Entity components

* refactor(gameplay): extract physics and collision from ClientPlayer into PhysicalSystem

Move per-axis collision detection and move distance calculation to new
PhysicalSystem. Move SpeedSystem implementation from inline header to
separate .cpp file. Add const accessors to Entity. Replace inline AABB
helper with HitboxManager registration of player hitbox using new
PLAYER_SIZE constant. Remove obsolete members and functions from
ClientPlayer.

* refactor(gameplay): integrate model and hitbox ID system into Entity

- Introduce HitboxID, EntityID, and ModelID types for safer ID-based lookups
- Replace AABB struct with Hitbox (includes HitboxID)
- Convert ModelManager and HitboxManager to singletons with Handle structs
- Update Entity to store IDs for model and hitbox, removing direct references
- Reorganize creature model assets into subdirectories per entity type
- Add player model (player.glb) and collision data for pig
- Remove ModelManager dependency from App and Renderer
- Add namespace parsing utility for asset paths
- Mark sparse_vector::insert() with [[nodiscard]]

* build: add entt library

* refactor(gameplay): rename ClientPlayer to LocalPlayer

* refactor(gameplay): separate player logic into manager and ECS components

* feat(gameplay): add entity managers and refactor to ECS components

* refactor(gameplay): replace client thread with timer-based system and add entity manager

* feat(gameplay): implement entity system with concurrent task handling and fix model loading

* feat(gameplay): add entity destruction support

* feat(entity): add client-to-server entity creation and destruction requests

Extend the network protocol with `C2SEntityCreateRequest` and `C2SEntityDestoryRequest` packets. Refactor entity managers to split public client-facing create/destroy methods that send requests over the network, from internal handlers that process received packets. Add utility functions for converting protobuf Vec3 to glm::vec3.

* feat(gameplay): implement entity update packets

Add S2CEntityUpdate to sync entity positions from server to client, including update handling in the client entity manager and server-side AI updates.

* feat(ai): add wander AI system with move boost

Add AIBase and WanderAITag components, a WanderAISystem, and a MoveBoost component to control wandering behavior. Replace the old MoveState with MoveBoost and include a horizontal random direction helper.

* refactor(ecs): move entity physics to tick-based systems

Update PhysicalSystem and SpeedSystem to operate on entt::registry
instead of individual components. Add TickVelocity for server creatures
so movement is calculated per tick without frame delta time. LocalPlayer
now implements its own client-side physics with collision detection.

* feat(gameplay): add server-side entity movement and AI

Refactor LocalPlayer::update_physical to operate on a passed position, and run speed, physical, and wander AI systems in ServerEntityManager.

* feat(gameplay): add pig wander AI and refine speed physics

* feat(server): send entity position updates to all sessions

* fix: correct velocity clamping and hitbox loading

Preserve sign when clamping velocity; negative velocities now clamp to zero instead of flipping direction. Support loading hitbox definitions from JSON arrays and objects. Tune pig entity movement, spawn height, and wander probabilities.

* feat(creatures): refine pig movement physics

Add movement constants for pigs and switch deceleration to per-axis friction so creatures stop naturally. Extend wander boost duration for smoother behavior.

* feat(physics): implement step-up for horizontal collisions

* feat: sync entity direction and rotate models accordingly

Move direction into the transform component and include it in server-to-client entity updates. Client now sets transform direction from the network message and uses it to compute yaw for model rotation, so entities visually face their movement direction. Refactor net_utils to support arbitrary Vec3 fields.

* feat(render): interpolate entity transforms for rendering

Add RenderTransform component to smooth position/direction updates
and use it in entity and shadow passes.

* fix(server_world): send time before entity updates

* build: replace nlohmann json with rapidjson

* refactor(json): migrate from nlohmann to rapidjson

Replace nlohmann::json with rapidjson across localization, hitbox manager, server world, and sensitive filter. Add json_utils helper for converting rapidjson documents to maps, and improve parse error handling.

* feat(item): add item manager with JSON asset loading

Implement ItemManager to load and query item definitions from assets/item JSON files. Add ItemData struct, item asset metadata, CMake source registration, and initialize the manager during app startup. Also add AGENTS.md repository guidelines.

* refactor(item): decouple items from block types

The item system now supports an ItemKind and property, allowing item JSON to declare a type instead of assuming every item is a block. BlockManager was moved to its own header, redesigned around concurrent hash maps, and exposes id_from_name(). Texture and UI code now key items by ItemID, while block placement resolves the block type from the item registry.

* fix(gameplay): use inline const for static EMPTY members

Use inline const for static EMPTY members to avoid ODR and linker issues.
Add missing block_manager.hpp includes in gameplay sources.

* fix: stabilize block item registration and display

Store item names as owned strings in ItemManager, set block type
property for block items, validate item kind before placement, and
handle items without textures gracefully in inventory UI.

* feat: add pig spawn egg item

Add pig spawn egg asset and texture, parse spawn egg item kind and creature property, and spawn the configured entity when used on an empty block. Also fix item texture loading to use actual image dimensions and update selected item UI sizing.

* refactor(gameplay): update systems per entity with chunk check

Refactor server entity update flow to process entities individually,
skipping those whose chunk is not loaded. System update methods now
accept a single entity instead of iterating the full registry view,
and `ServerWorld::get_chunk_ref_count` is added to determine if an
entity's chunk is active.

* perf(render): skip entities outside loaded chunks

* feat: add --direct-enter option to skip to world scene

Support a new CLI flag that launches the app directly into the world scene. If no IP is provided, it starts a local server on the specified port and connects to 127.0.0.1; otherwise it connects to the given IP. With this flag enabled, a port must be specified via -p. Also expose SceneManager::push as public so scenes can be pushed immediately when bypassing the normal menu flow.

* refactor(localization): switch block translations to item naming

Remove the `name_key` field from block definitions and use item-based
localization keys (`item.*.name`) for inventory display. Item data now
stores the localized name at load time.

* feat(gameplay): spawn creatures during chunk generation

Add creature spawning to chunk generation with a configurable
SpawnConfig, including a default pig spawn. Spawning occurs in
the final generation phase and registers entities through the
server world's entity manager.

Also destroy entities when their chunk is unloaded to prevent
orphaned entities and expose the entity manager from ServerWorld.

* feat(gameplay): add run mode based thread pool config

Introduce RunMode enum and thread pool sizing helpers for client,
server, and hybrid modes. Add compute pool to server world and pass
mode through server/client initialization.

* perf(server): parallelize entity update loop

Use parallel_do to process entities concurrently via the compute
pool. Switch get_all_session to a thread-safe
tbb::concurrent_vector and make ChunkEntity's ref_count atomic to
avoid data races. Also remove the debug pig spawn from world init.

* feat(creatures): animate creature walk cycles

Add a Gait component synchronized over the network and procedural animation for model nodes. Load animation parameters from assets/model/creature/pig/animation.json and apply leg swing, body bob, and head motion based on gait. Refactor Gait into its own header for reuse.

* fix(gameplay): make entity interpolation frame-rate independent

* perf(render): batch model rendering with instancing

Replaces per-entity draw calls with instanced rendering for both main and shadow passes. Each model's node hierarchy is flattened once and instance matrices are updated per frame, reducing draw calls and CPU overhead.

* refactor(render): build entity instance buffers once per frame

Move instance matrix upload into build_vertices and use a precomputed
instance data map for both shadow and color passes, avoiding duplicate
GPU buffer updates.

* perf(gameplay): batch entity updates into single packet

Aggregate per-entity update messages into S2CEntityUpdateBatch and
broadcast once per tick. Reuse serialized packets in several broadcast
loops to avoid repeated make_packet calls.

* fix: correct thread count and shadow projection uniform

- Add reserved client thread count to client threads in server generation calculation.
- Set projection matrix uniform only for non-shadow rendering.

* feat(ecs): add entity type separation and creature limits

Replace generic entity creation with typed creatures and items. Rename `add_entity` to `add_creature`, enforce per-player creature cap, and track entity/creature totals for metrics. Expose run mode to dev panel and show new counts.

* perf(render): frustum cull entities before instance building

Add frustum culling to entity instance data collection using AABB vs camera frustum planes. Pass renderer into get_instances_data_map to compute MVP and extract planes. Also add "Rendered Entities" debug counter for visibility.

* feat(audio): add ambient pig sounds

Add pig call audio with randomized timing, triggered by proximity to the player as 3D positional sound.

* feat(client-entity): use snapshot history for entity interpolation

Replace exponential smoothing with a buffered snapshot system. Each entity keeps a deque of position/direction snapshots with timestamps; the render transform is interpolated at a fixed 100 ms render delay to hide network jitter. Snapshots are capped to 16 entries.

* refactor(hitbox): move player hitbox definition to JSON asset

* feat(client_player): use snapshot interpolation for remote players

Replace exponential position smoothing with snapshot interpolation. Remote player transforms are rendered from a delayed snapshot history, using linear interpolation for position and shortest-path interpolation for yaw/pitch. A 100 ms render delay compensates for network tick rate.

include/entt/resource/cache.hpp

@@ -0,0 +1,386 @@
+#ifndef ENTT_RESOURCE_RESOURCE_CACHE_HPP
+#define ENTT_RESOURCE_RESOURCE_CACHE_HPP
+
+#include <compare>
+#include "../container/dense_map.hpp"
+#include "../core/compressed_pair.hpp"
+#include "../core/fwd.hpp"
+#include "../core/iterator.hpp"
+#include "../stl/concepts.hpp"
+#include "../stl/cstddef.hpp"
+#include "../stl/functional.hpp"
+#include "../stl/iterator.hpp"
+#include "../stl/memory.hpp"
+#include "../stl/tuple.hpp"
+#include "../stl/type_traits.hpp"
+#include "../stl/utility.hpp"
+#include "fwd.hpp"
+#include "loader.hpp"
+#include "resource.hpp"
+
+namespace entt {
+
+/*! @cond ENTT_INTERNAL */
+namespace internal {
+
+template<typename Type, typename It>
+class resource_cache_iterator final {
+    template<typename, typename>
+    friend class resource_cache_iterator;
+
+public:
+    using value_type = stl::pair<id_type, resource<Type>>;
+    using pointer = input_iterator_pointer<value_type>;
+    using reference = value_type;
+    using difference_type = stl::ptrdiff_t;
+    using iterator_category = stl::input_iterator_tag;
+    using iterator_concept = stl::random_access_iterator_tag;
+
+    constexpr resource_cache_iterator() noexcept = default;
+
+    constexpr resource_cache_iterator(const It iter) noexcept
+        : it{iter} {}
+
+    template<typename Other>
+    requires (!stl::same_as<It, Other> && stl::constructible_from<It, Other>)
+    constexpr resource_cache_iterator(const resource_cache_iterator<stl::remove_const_t<Type>, Other> &other) noexcept
+        : it{other.it} {}
+
+    constexpr resource_cache_iterator &operator++() noexcept {
+        return ++it, *this;
+    }
+
+    constexpr resource_cache_iterator operator++(int) noexcept {
+        const resource_cache_iterator orig = *this;
+        return ++(*this), orig;
+    }
+
+    constexpr resource_cache_iterator &operator--() noexcept {
+        return --it, *this;
+    }
+
+    constexpr resource_cache_iterator operator--(int) noexcept {
+        const resource_cache_iterator orig = *this;
+        return operator--(), orig;
+    }
+
+    constexpr resource_cache_iterator &operator+=(const difference_type value) noexcept {
+        it += value;
+        return *this;
+    }
+
+    constexpr resource_cache_iterator operator+(const difference_type value) const noexcept {
+        resource_cache_iterator copy = *this;
+        return (copy += value);
+    }
+
+    constexpr resource_cache_iterator &operator-=(const difference_type value) noexcept {
+        return (*this += -value);
+    }
+
+    constexpr resource_cache_iterator operator-(const difference_type value) const noexcept {
+        return (*this + -value);
+    }
+
+    [[nodiscard]] constexpr reference operator[](const difference_type value) const noexcept {
+        return {it[value].first, resource<Type>{it[value].second}};
+    }
+
+    [[nodiscard]] constexpr reference operator*() const noexcept {
+        return operator[](0);
+    }
+
+    [[nodiscard]] constexpr pointer operator->() const noexcept {
+        return operator*();
+    }
+
+    template<typename... Args>
+    [[nodiscard]] constexpr stl::ptrdiff_t operator-(const resource_cache_iterator<Args...> &other) const noexcept {
+        return it - other.it;
+    }
+
+    template<typename... Args>
+    [[nodiscard]] constexpr bool operator==(const resource_cache_iterator<Args...> &other) const noexcept {
+        return it == other.it;
+    }
+
+    template<typename... Args>
+    [[nodiscard]] constexpr auto operator<=>(const resource_cache_iterator<Args...> &other) const noexcept {
+        return it <=> other.it;
+    }
+
+private:
+    It it;
+};
+
+} // namespace internal
+/*! @endcond */
+
+/**
+ * @brief Basic cache for resources of any type.
+ * @tparam Type Type of resources managed by a cache.
+ * @tparam Loader Type of loader used to create the resources.
+ * @tparam Allocator Type of allocator used to manage memory and elements.
+ */
+template<typename Type, typename Loader, typename Allocator>
+class resource_cache {
+    using alloc_traits = stl::allocator_traits<Allocator>;
+    static_assert(stl::is_same_v<typename alloc_traits::value_type, Type>, "Invalid value type");
+    using container_allocator = alloc_traits::template rebind_alloc<stl::pair<const id_type, typename Loader::result_type>>;
+    using container_type = dense_map<id_type, typename Loader::result_type, stl::identity, stl::equal_to<>, container_allocator>;
+
+public:
+    /*! @brief Allocator type. */
+    using allocator_type = Allocator;
+    /*! @brief Resource type. */
+    using value_type = Type;
+    /*! @brief Unsigned integer type. */
+    using size_type = stl::size_t;
+    /*! @brief Loader type. */
+    using loader_type = Loader;
+    /*! @brief Input iterator type. */
+    using iterator = internal::resource_cache_iterator<Type, typename container_type::iterator>;
+    /*! @brief Constant input iterator type. */
+    using const_iterator = internal::resource_cache_iterator<const Type, typename container_type::const_iterator>;
+
+    /*! @brief Default constructor. */
+    resource_cache()
+        : resource_cache{loader_type{}} {}
+
+    /**
+     * @brief Constructs an empty cache with a given allocator.
+     * @param allocator The allocator to use.
+     */
+    explicit resource_cache(const allocator_type &allocator)
+        : resource_cache{loader_type{}, allocator} {}
+
+    /**
+     * @brief Constructs an empty cache with a given allocator and loader.
+     * @param callable The loader to use.
+     * @param allocator The allocator to use.
+     */
+    explicit resource_cache(const loader_type &callable, const allocator_type &allocator = allocator_type{})
+        : pool{container_type{allocator}, callable} {}
+
+    /*! @brief Default copy constructor. */
+    resource_cache(const resource_cache &) = default;
+
+    /**
+     * @brief Allocator-extended copy constructor.
+     * @param other The instance to copy from.
+     * @param allocator The allocator to use.
+     */
+    resource_cache(const resource_cache &other, const allocator_type &allocator)
+        : pool{stl::piecewise_construct, stl::forward_as_tuple(other.pool.first(), allocator), stl::forward_as_tuple(other.pool.second())} {}
+
+    /*! @brief Default move constructor. */
+    resource_cache(resource_cache &&) noexcept = default;
+
+    /**
+     * @brief Allocator-extended move constructor.
+     * @param other The instance to move from.
+     * @param allocator The allocator to use.
+     */
+    resource_cache(resource_cache &&other, const allocator_type &allocator)
+        : pool{stl::piecewise_construct, stl::forward_as_tuple(stl::move(other.pool.first()), allocator), stl::forward_as_tuple(stl::move(other.pool.second()))} {}
+
+    /*! @brief Default destructor. */
+    ~resource_cache() = default;
+
+    /**
+     * @brief Default copy assignment operator.
+     * @return This cache.
+     */
+    resource_cache &operator=(const resource_cache &) = default;
+
+    /**
+     * @brief Default move assignment operator.
+     * @return This cache.
+     */
+    resource_cache &operator=(resource_cache &&) noexcept = default;
+
+    /**
+     * @brief Returns the associated allocator.
+     * @return The associated allocator.
+     */
+    [[nodiscard]] constexpr allocator_type get_allocator() const noexcept {
+        return pool.first().get_allocator();
+    }
+
+    /**
+     * @brief Returns an iterator to the beginning.
+     *
+     * If the cache is empty, the returned iterator will be equal to `end()`.
+     *
+     * @return An iterator to the first instance of the internal cache.
+     */
+    [[nodiscard]] const_iterator cbegin() const noexcept {
+        return pool.first().begin();
+    }
+
+    /*! @copydoc cbegin */
+    [[nodiscard]] const_iterator begin() const noexcept {
+        return cbegin();
+    }
+
+    /*! @copydoc begin */
+    [[nodiscard]] iterator begin() noexcept {
+        return pool.first().begin();
+    }
+
+    /**
+     * @brief Returns an iterator to the end.
+     * @return An iterator to the element following the last instance of the
+     * internal cache.
+     */
+    [[nodiscard]] const_iterator cend() const noexcept {
+        return pool.first().end();
+    }
+
+    /*! @copydoc cend */
+    [[nodiscard]] const_iterator end() const noexcept {
+        return cend();
+    }
+
+    /*! @copydoc end */
+    [[nodiscard]] iterator end() noexcept {
+        return pool.first().end();
+    }
+
+    /**
+     * @brief Returns true if a cache contains no resources, false otherwise.
+     * @return True if the cache contains no resources, false otherwise.
+     */
+    [[nodiscard]] bool empty() const noexcept {
+        return pool.first().empty();
+    }
+
+    /**
+     * @brief Number of resources managed by a cache.
+     * @return Number of resources currently stored.
+     */
+    [[nodiscard]] size_type size() const noexcept {
+        return pool.first().size();
+    }
+
+    /*! @brief Clears a cache. */
+    void clear() noexcept {
+        pool.first().clear();
+    }
+
+    /**
+     * @brief Loads a resource, if its identifier does not exist.
+     *
+     * Arguments are forwarded directly to the loader and _consumed_ only if the
+     * resource doesn't already exist.
+     *
+     * @warning
+     * If the resource isn't loaded correctly, the returned handle could be
+     * invalid and any use of it will result in undefined behavior.
+     *
+     * @tparam Args Types of arguments to use to load the resource if required.
+     * @param id Unique resource identifier.
+     * @param args Arguments to use to load the resource if required.
+     * @return A pair consisting of an iterator to the inserted element (or to
+     * the element that prevented the insertion) and a bool denoting whether the
+     * insertion took place.
+     */
+    template<typename... Args>
+    stl::pair<iterator, bool> load(const id_type id, Args &&...args) {
+        if(auto it = pool.first().find(id); it != pool.first().end()) {
+            return {it, false};
+        }
+
+        return pool.first().emplace(id, pool.second()(stl::forward<Args>(args)...));
+    }
+
+    /**
+     * @brief Force loads a resource, even if its identifier already exists.
+     * @copydetails load
+     */
+    template<typename... Args>
+    stl::pair<iterator, bool> force_load(const id_type id, Args &&...args) {
+        return {pool.first().insert_or_assign(id, pool.second()(stl::forward<Args>(args)...)).first, true};
+    }
+
+    /**
+     * @brief Returns a handle for a given resource identifier.
+     *
+     * @warning
+     * There is no guarantee that the returned handle is valid.<br/>
+     * If it is not, any use will result in undefined behavior.
+     *
+     * @param id Unique resource identifier.
+     * @return A handle for the given resource.
+     */
+    [[nodiscard]] resource<const value_type> operator[](const id_type id) const {
+        if(auto it = pool.first().find(id); it != pool.first().cend()) {
+            return resource<const value_type>{it->second};
+        }
+
+        return {};
+    }
+
+    /*! @copydoc operator[] */
+    [[nodiscard]] resource<value_type> operator[](const id_type id) {
+        if(auto it = pool.first().find(id); it != pool.first().end()) {
+            return resource<value_type>{it->second};
+        }
+
+        return {};
+    }
+
+    /**
+     * @brief Checks if a cache contains a given identifier.
+     * @param id Unique resource identifier.
+     * @return True if the cache contains the resource, false otherwise.
+     */
+    [[nodiscard]] bool contains(const id_type id) const {
+        return pool.first().contains(id);
+    }
+
+    /**
+     * @brief Removes an element from a given position.
+     * @param pos An iterator to the element to remove.
+     * @return An iterator following the removed element.
+     */
+    iterator erase(const_iterator pos) {
+        const auto it = pool.first().begin();
+        return pool.first().erase(it + (pos - const_iterator{it}));
+    }
+
+    /**
+     * @brief Removes the given elements from a cache.
+     * @param first An iterator to the first element of the range of elements.
+     * @param last An iterator past the last element of the range of elements.
+     * @return An iterator following the last removed element.
+     */
+    iterator erase(const_iterator first, const_iterator last) {
+        const auto it = pool.first().begin();
+        return pool.first().erase(it + (first - const_iterator{it}), it + (last - const_iterator{it}));
+    }
+
+    /**
+     * @brief Removes the given elements from a cache.
+     * @param id Unique resource identifier.
+     * @return Number of resources erased (either 0 or 1).
+     */
+    size_type erase(const id_type id) {
+        return pool.first().erase(id);
+    }
+
+    /**
+     * @brief Returns the loader used to create resources.
+     * @return The loader used to create resources.
+     */
+    [[nodiscard]] loader_type loader() const {
+        return pool.second();
+    }
+
+private:
+    compressed_pair<container_type, loader_type> pool;
+};
+
+} // namespace entt
+
+#endif

include/entt/resource/fwd.hpp

@@ -0,0 +1,19 @@
+#ifndef ENTT_RESOURCE_FWD_HPP
+#define ENTT_RESOURCE_FWD_HPP
+
+#include "../stl/memory.hpp"
+
+namespace entt {
+
+template<typename>
+struct resource_loader;
+
+template<typename Type, typename = resource_loader<Type>, typename = stl::allocator<Type>>
+class resource_cache;
+
+template<typename>
+class resource;
+
+} // namespace entt
+
+#endif

include/entt/resource/loader.hpp

@@ -0,0 +1,33 @@
+#ifndef ENTT_RESOURCE_LOADER_HPP
+#define ENTT_RESOURCE_LOADER_HPP
+
+#include "../stl/memory.hpp"
+#include "../stl/utility.hpp"
+#include "fwd.hpp"
+
+namespace entt {
+
+/**
+ * @brief Transparent loader for shared resources.
+ * @tparam Type Type of resources created by the loader.
+ */
+template<typename Type>
+struct resource_loader {
+    /*! @brief Result type. */
+    using result_type = stl::shared_ptr<Type>;
+
+    /**
+     * @brief Constructs a shared pointer to a resource from its arguments.
+     * @tparam Args Types of arguments to use to construct the resource.
+     * @param args Parameters to use to construct the resource.
+     * @return A shared pointer to a resource of the given type.
+     */
+    template<typename... Args>
+    result_type operator()(Args &&...args) const {
+        return stl::make_shared<Type>(stl::forward<Args>(args)...);
+    }
+};
+
+} // namespace entt
+
+#endif

include/entt/resource/resource.hpp

@@ -0,0 +1,212 @@
+#ifndef ENTT_RESOURCE_RESOURCE_HPP
+#define ENTT_RESOURCE_RESOURCE_HPP
+
+#include <compare>
+#include "../stl/concepts.hpp"
+#include "../stl/memory.hpp"
+#include "../stl/utility.hpp"
+#include "fwd.hpp"
+
+namespace entt {
+
+/**
+ * @brief Basic resource handle.
+ *
+ * A handle wraps a resource and extends its lifetime. It also shares the same
+ * resource with all other handles constructed from the same element.<br/>
+ * As a rule of thumb, resources should never be copied nor moved. Handles are
+ * the way to go to push references around.
+ *
+ * @tparam Type Type of resource managed by a handle.
+ */
+template<typename Type>
+class resource {
+    template<typename>
+    friend class resource;
+
+public:
+    /*! @brief Resource type. */
+    using element_type = Type;
+    /*! @brief Handle type. */
+    using handle_type = stl::shared_ptr<element_type>;
+
+    /*! @brief Default constructor. */
+    resource() noexcept
+        : value{} {}
+
+    /**
+     * @brief Creates a new resource handle.
+     * @param res A handle to a resource.
+     */
+    explicit resource(handle_type res) noexcept
+        : value{stl::move(res)} {}
+
+    /*! @brief Default copy constructor. */
+    resource(const resource &) noexcept = default;
+
+    /*! @brief Default move constructor. */
+    resource(resource &&) noexcept = default;
+
+    /**
+     * @brief Aliasing constructor.
+     * @tparam Other Type of resource managed by the received handle.
+     * @param other The handle with which to share ownership information.
+     * @param res Unrelated and unmanaged resources.
+     */
+    template<typename Other>
+    resource(const resource<Other> &other, element_type &res) noexcept
+        : value{other.value, stl::addressof(res)} {}
+
+    /**
+     * @brief Copy constructs a handle which shares ownership of the resource.
+     * @tparam Other Type of resource managed by the received handle.
+     * @param other The handle to copy from.
+     */
+    template<typename Other>
+    requires (!stl::same_as<Type, Other> && stl::constructible_from<Type &, Other &>)
+    resource(const resource<Other> &other) noexcept
+        : value{other.value} {}
+
+    /**
+     * @brief Move constructs a handle which takes ownership of the resource.
+     * @tparam Other Type of resource managed by the received handle.
+     * @param other The handle to move from.
+     */
+    template<typename Other>
+    requires (!stl::same_as<Type, Other> && stl::constructible_from<Type &, Other &>)
+    resource(resource<Other> &&other) noexcept
+        : value{stl::move(other.value)} {}
+
+    /*! @brief Default destructor. */
+    ~resource() = default;
+
+    /**
+     * @brief Default copy assignment operator.
+     * @return This resource handle.
+     */
+    resource &operator=(const resource &) noexcept = default;
+
+    /**
+     * @brief Default move assignment operator.
+     * @return This resource handle.
+     */
+    resource &operator=(resource &&) noexcept = default;
+
+    /**
+     * @brief Copy assignment operator from foreign handle.
+     * @tparam Other Type of resource managed by the received handle.
+     * @param other The handle to copy from.
+     * @return This resource handle.
+     */
+    template<typename Other>
+    requires (!stl::same_as<Type, Other> && stl::constructible_from<Type &, Other &>)
+    resource &operator=(const resource<Other> &other) noexcept {
+        value = other.value;
+        return *this;
+    }
+
+    /**
+     * @brief Move assignment operator from foreign handle.
+     * @tparam Other Type of resource managed by the received handle.
+     * @param other The handle to move from.
+     * @return This resource handle.
+     */
+    template<typename Other>
+    requires (!stl::same_as<Type, Other> && stl::constructible_from<Type &, Other &>)
+    resource &operator=(resource<Other> &&other) noexcept {
+        value = stl::move(other.value);
+        return *this;
+    }
+
+    /**
+     * @brief Exchanges the content with that of a given resource.
+     * @param other Resource to exchange the content with.
+     */
+    void swap(resource &other) noexcept {
+        using stl::swap;
+        swap(value, other.value);
+    }
+
+    /**
+     * @brief Returns a reference to the managed resource.
+     *
+     * @warning
+     * The behavior is undefined if the handle doesn't contain a resource.
+     *
+     * @return A reference to the managed resource.
+     */
+    [[nodiscard]] element_type &operator*() const noexcept {
+        return *value;
+    }
+
+    /*! @copydoc operator* */
+    [[nodiscard]] operator element_type &() const noexcept {
+        return *value;
+    }
+
+    /**
+     * @brief Returns a pointer to the managed resource.
+     * @return A pointer to the managed resource.
+     */
+    [[nodiscard]] element_type *operator->() const noexcept {
+        return value.get();
+    }
+
+    /**
+     * @brief Returns true if a handle contains a resource, false otherwise.
+     * @return True if the handle contains a resource, false otherwise.
+     */
+    [[nodiscard]] explicit operator bool() const noexcept {
+        return static_cast<bool>(value);
+    }
+
+    /**
+     * @brief Compares two handles.
+     * @tparam Other Type of resource managed by the other handle.
+     * @param other A valid handle.
+     * @return True if both handles refer to the same resource, false otherwise.
+     */
+    template<typename Other>
+    [[nodiscard]] bool operator==(const resource<Other> &other) const noexcept {
+        return (value == other.value);
+    }
+
+    /**
+     * @brief Lexicographically compares two handles.
+     * @tparam Other Type of resource managed by the other handle.
+     * @param other A valid handle.
+     * @return The relative order between the two handles.
+     */
+    template<typename Other>
+    [[nodiscard]] auto operator<=>(const resource<Other> &other) const noexcept {
+        return (value <=> other.value);
+    }
+
+    /*! @brief Releases the ownership of the managed resource. */
+    void reset() {
+        value.reset();
+    }
+
+    /**
+     * @brief Replaces the managed resource.
+     * @param other A handle to a resource.
+     */
+    void reset(handle_type other) {
+        value = stl::move(other);
+    }
+
+    /**
+     * @brief Returns the underlying resource handle.
+     * @return The underlying resource handle.
+     */
+    [[nodiscard]] handle_type handle() const noexcept {
+        return value;
+    }
+
+private:
+    handle_type value;
+};
+
+} // namespace entt
+
+#endif