diff --git a/src/engine.cpp b/src/engine.cpp index 6b96cb4534..f9f65b5e8f 100644 --- a/src/engine.cpp +++ b/src/engine.cpp @@ -591,6 +591,14 @@ EngineID EngineOverrideManager::UseUnreservedID(VehicleType type, uint16_t grf_l return it->engine; } +/** + * Create an override to the given engine. If the override already exists, it will be overwritten. + * @param type The vehicle type. + * @param grf_local_id The NewGRF internal identifier. + * @param grfid The unique identifier of the NewGRF. + * @param substitute_id The fallback original engine. + * @param engine The engine this override is for. + */ void EngineOverrideManager::SetID(VehicleType type, uint16_t grf_local_id, GrfID grfid, uint8_t substitute_id, EngineID engine) { auto &map = this->mappings[type]; diff --git a/src/engine_base.h b/src/engine_base.h index 0b15d3dcce..e27e0e4397 100644 --- a/src/engine_base.h +++ b/src/engine_base.h @@ -207,11 +207,31 @@ struct EngineIDMapping { uint8_t substitute_id = 0; ///< The (original) entity ID to use if this GRF is not available (currently not used) EngineID engine{}; + /** + * Create a 64 bit key from the GRFID and internal ID for mappings. + * @param grfid The NewGRF id. + * @param internal_id The internal ID within the GRF file. + * @return The key. + */ static inline uint64_t Key(GrfID grfid, uint16_t internal_id) { return static_cast(grfid) << 32 | internal_id; } + /** + * Create a 64 bit key from this mapping. + * @return The key. + */ inline uint64_t Key() const { return Key(this->grfid, this->internal_id); } + /** Create a new mapping. */ EngineIDMapping() {} + + /** + * Create the mapping. + * @param grfid The unique identifer of the NewGRF. + * @param internal_id The internal identifier of the engine within the NewGRF. + * @param type The vehicle type. + * @param substitute_id The original vehicle to fall back to. + * @param engine The engine the mapping is for. + */ EngineIDMapping(GrfID grfid, uint16_t internal_id, VehicleType type, uint8_t substitute_id, EngineID engine) : grfid(grfid), internal_id(internal_id), type(type), substitute_id(substitute_id), engine(engine) {} }; diff --git a/src/newgrf/newgrf_actd.cpp b/src/newgrf/newgrf_actd.cpp index 2772a575df..e55d852a91 100644 --- a/src/newgrf/newgrf_actd.cpp +++ b/src/newgrf/newgrf_actd.cpp @@ -132,6 +132,15 @@ static uint32_t GetPatchVariable(uint8_t param) } } +/** + * Performs the GRF Resource Management, where NewGRFs can cooperatively manage sprite resources. + * @param grm Mapping to the NewGRF linked with a resource. + * @param count The number of elements to process. + * @param op The operation to perform. + * @param target The target for the operation. + * @param type Name of type for debug messages. + * @return Operation/target specific result. + */ static uint32_t PerformGRM(std::span grm, uint16_t count, uint8_t op, uint8_t target, std::string_view type) { uint start = 0; diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp index e6643bfb0a..26cac9b066 100644 --- a/src/newgrf_house.cpp +++ b/src/newgrf_house.cpp @@ -136,6 +136,12 @@ void ResetHouseClassIDs() _class_mapping.emplace_back(); } +/** + * Allocate a house class for the given NewGRF and ID. + * @param grf_class_id The class id within the NewGRF. + * @param grfid The GRF this class belongs to. + * @return The existing allocation, or a new one when it did not exist yet. + */ HouseClassID AllocateHouseClassID(uint8_t grf_class_id, GrfID grfid) { /* Start from 1 because 0 means that no class has been assigned. */ diff --git a/src/newgrf_storage.h b/src/newgrf_storage.h index 409074ff94..abb06e12ec 100644 --- a/src/newgrf_storage.h +++ b/src/newgrf_storage.h @@ -198,6 +198,13 @@ extern PersistentStoragePool _persistent_storage_pool; * Class for pooled persistent storage of data. */ struct PersistentStorage : PersistentStorageArray, PersistentStoragePool::PoolItem<&_persistent_storage_pool> { + /** + * Create the pooled storage. + * @param index The unique identifier of the pool item. + * @param grfid The NewGRF this storage is of. + * @param feature The feature associated with this storage. + * @param tile The tile associated with this storage. + */ PersistentStorage(PersistentStorageID index, GrfID grfid, GrfSpecFeature feature, TileIndex tile) : PersistentStoragePool::PoolItem<&_persistent_storage_pool>(index) { this->grfid = grfid; diff --git a/src/newgrf_townname.cpp b/src/newgrf_townname.cpp index d83f8eecfc..ebd5e222b8 100644 --- a/src/newgrf_townname.cpp +++ b/src/newgrf_townname.cpp @@ -24,6 +24,11 @@ static std::vector _grf_townnames; static std::vector _grf_townname_names; +/** + * Get the \c GRFTownName for the given GRFID. + * @param grfid The GRFID of the town name. + * @return The \c GRFTownName or \c nullptr if it does not exist. + */ GRFTownName *GetGRFTownName(GrfID grfid) { auto found = std::ranges::find(_grf_townnames, grfid, &GRFTownName::grfid); @@ -31,6 +36,11 @@ GRFTownName *GetGRFTownName(GrfID grfid) return nullptr; } +/** + * Get the \c GRFTownName for the given GRFID or allocate one if it does not exist. + * @param grfid The GRFID of the town name. + * @return The \c GRFTownName. + */ GRFTownName *AddGRFTownName(GrfID grfid) { GRFTownName *t = GetGRFTownName(grfid); @@ -41,6 +51,10 @@ GRFTownName *AddGRFTownName(GrfID grfid) return t; } +/** + * Remove the \c GRFTownName mapping for the given GRFID. + * @param grfid The NewGRF to remove for. + */ void DelGRFTownName(GrfID grfid) { _grf_townnames.erase(std::ranges::find(_grf_townnames, grfid, &GRFTownName::grfid)); @@ -66,6 +80,13 @@ static void RandomPart(StringBuilder &builder, const GRFTownName *t, uint32_t se } } +/** + * Construct a NewGRF town name into the builder. + * @param builder The string builder to write to. + * @param grfid The NewGRF providing the information/logic. + * @param gen The town name style to get from the NewGRF. + * @param seed The random 32 bit number to generate the town name for. + */ void GRFTownNameGenerate(StringBuilder &builder, GrfID grfid, uint16_t gen, uint32_t seed) { const GRFTownName *t = GetGRFTownName(grfid);