NML:Houses
From GRFSpecs
Revision as of 17:46, 2 September 2012 by Hirundo (talk | contribs) (→House callbacks: Improve documentation of animation callbacks)
Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain
- common props | vars | CBs
- train | roadveh | ship | aircr props
- common variables
- industry props | vars | CBs
- tile props | vars | CBs
- airport props | vars | CBs
- tile props | vars | CBs
House properties
| property | value range | comment | |
|---|---|---|---|
| name | string | for example string(STR_NAME_EIFFEL_TOWER) | |
| substitute | 0 ... 109 | Number of the default house that replaces this one, if this house is not available for some reason. This property must be set first, before any other properties or graphics. All properties of the old type are copied to your new house, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of default house types for a list of possible substitute IDs. | |
| override | 0 ... 109 | id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of default house types. | |
| building_flags. | bitmask(HOUSE_FLAG_XXX,...) |
| |
| population | 0 ... 255 | number of inhabitants the building adds to the town, if present | |
| mail_multiplier | 0 ... 255 | ||
| pax_acceptance | 0 ... 1 | Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1. | |
| mail_acceptance | 0 ... 1 | ||
| cargo_acceptance | 0 ... 1 | Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
| |
| accepted_cargo | up to three cargo labels, e.g. MAIL, PASS, COAL | ||
| local_authority_impact | 0 ... 65525 | amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding). | |
| removal_cost_multiplier | 0 ... 255 | ||
| probability | 0 ... 16 (float) | Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1. | |
| years_available | array of two int | [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built | |
| minimum_lifetime | 0 ... 255 | number of years the building will remain at least | |
| availability_mask |
[bitmask(town zones), bitmask(CLIMATE_XXX, ...)] |
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline.
| |
| callback_flags | bitmask(HOUSE_CBF_XX) |
Do not set this, unless you use old-style callbacks. | |
| random_colours | array of 4, each COLOUR_XXX |
colour values in an array, refer to the table here for a list of possible values. | |
| refresh_multiplier | 0 ... 63 | Defines the frequency with which the tile will be re-randomized which has an impact for random animation. | |
| animation_info | Array [ANIMATION_XXX, frame-count] |
Type of animation and its length (1...128 frames):
| |
| animation_speed | 2 ... 16 |
Speed of animation, see animation speed table for the meaning of the values. | |
| building_class | 0 .. 255 | An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation | |
| watched_cargo_types | array of values from your cargo table |  1.2  2.6List of cargo types to watch, to be used with the watched_cargo_accepted callback.
|
House variables
| name | value range | comment |
|---|---|---|
| construction_state | 0..3 | Current construction state of the industry tile |
| pseudo_random_bits | 0..3 | Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance. |
| age | 0..255 | Age of the house in years, limited to 255 |
| town_zone | The town zone of the current tile | |
| terrain_type | TILETYPE_XX | TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW |
| same_house_count_town | 0..255 | Number of the houses with the same ID in the same town as this house |
| same_house_count_map | 0..255 | Number of the houses with the same ID on the entire map |
| same_class_count_town | 0..255 | Number of the houses with the same building_class in the same town as this house
|
| same_class_count_map | 0..255 | Number of the houses with the same building_class on the entire map
|
| generating_town | [0 | 1] | 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, town variables population and building_count are incorrect. The population variable contains the population of buildings generated yet, the final value may be larger. The building_count is surely higher than the final value will be.
|
| animation_frame | 0..255 | Current animation frame |
| x_coordinate | 0..2047 | X-coordinate (top right -> bottom left) of the tile on the map |
| y_coordinate | 0..2047 | Y-coordinate (top left -> bottom right) of the tile on the map |
The following variables require one or more arguments
| name | arguments | value range | comment |
|---|---|---|---|
| old_house_count_town | ID of old house type (0..109) | 0..255 | Number of old houses with a given ID in the same town as the current house |
| old_house_count_town | ID of old house type (0..109) | 0..255 | Number of old houses with a given ID on the whole map |
| other_house_count_town | ID of house defined in this NewGRF (0..255) | 0..255 | Number of houses with a given ID in the same town as the current house |
| other_house_count_map | ID of house defined in this NewGRF (0..255) | 0..255 | Number of houses with a given ID on the whole map |
| other_class_count_town | ID of house defined in this NewGRF (0..255) | 0..255 | Number of houses, with the same class as the house with the given ID, in the same town as the current house |
| other_class_count_map | ID of house defined in this NewGRF (0..255) | 0..255 | Number of houses, with the same class as the house with the given ID, on the whole map |
| nearby_tile_slope | x- and y-offset (both signed, range -8..7) | SLOPE_XXX | See tile slopes for an overview of possible values |
| nearby_tile_is_water | x- and y-offset (both signed, range -8..7) | [0 | 1] | 1 if the tile is water, 0 otherwise |
| nearby_tile_terrain_type | x- and y-offset (both signed, range -8..7) | TILETYPE_XX | TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW |
| nearby_tile_water_class | x- and y-offset (both signed, range -8..7) | WATER_CLASS_XXX | XXX = [NONE | SEA | CANAL | RIVER] Note that tiles for which nearby_tile_is_water is 0 may still have a water class, e.g. industry tiles with water beneath them.
|
| nearby_tile_height | x- and y-offset (both signed, range -8..7) | 0..255 (currently limited to 0..15) | Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels. |
| nearby_tile_class | x- and y-offset (both signed, range -8..7) | ||
| nearby_tile_animation_frame | x- and y-offset (both signed, range -8..7) | 0..255 | Animation frame of the given tile |
| cargo_accepted_nearby_ever | cargo type, x- and y-offset [1] | [0 | 1] | 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise |
| cargo_accepted_nearby_last_month | cargo type, x- and y-offset [1] | [0 | 1] | 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise |
| cargo_accepted_nearby_this_month | cargo type, x- and y-offset [1] | [0 | 1] | 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise |
| cargo_accepted_nearby_last_bigtick | cargo type, x- and y-offset [1] | [0 | 1] | 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise |
| cargo_accepted_nearby_watched | cargo type, x- and y-offset [1] | [0 | 1] | 1 if the given cargo type was one of the cargo types that triggered the watched_cargo_accepted-callback (only during this callback), 0 otherwise
|
| nearest_house_matching_criterion | radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [ID | CLASS | GRFID]) | 1..63, or 0 if not found | Perform a circular search for a house matching either the id, building_class or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|
| nearby_tile_house_id | x- and y-offset (both signed, range -8..7) | -1, or 0 .. 767 | Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. |
| nearby_tile_house_class | x- and y-offset (both signed, range -8..7) | -1, 0, or 256 .. 767 | Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with building_class X or 512+X if the house has been defined by a different NewGRF with building_class X.
|
| nearby_tile_house_grfid | x- and y-offset (both signed, range -8..7) | -1, 0 or a GRFID | Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house. |
- ↑ 1.0 1.1 1.2 1.3 1.4 Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.
House callbacks
| callback | return value | comment |
|---|---|---|
| default | Sprite layout | Graphics for the house tile |
| random_trigger | N/A |
See random switch for more information. |
| anim_next_frame | Next animation frame or CB_RESULT_XXX | Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. extra_callback_info1 contains 32 random bits, if enabled in the building_flags property. Returning a sound effect in the high byte will cause that sound effect to be played.
|
| anim_control | Next animation frame or CB_RESULT_XXX | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. extra_callback_info1 contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the building_flags-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|
| construction_anim | Same as anim_control
|
Works the same as the anim_control callback, except that it's called when the construction state changes.
|
| watched_cargo_accepted | Same as anim_control
|
Works the same as the anim_control callback, except that it's called when one of the watched cargo types is accepted.
|
| anim_speed | 0 .. 16 | Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes. |
| cargo_type_accept | type1 + (type2 << 5) + (type3 << 10) | Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from accepted_cargo are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|
| cargo_amount_accept | amt1 + (amt2 << 4) + (amt3 << 8) | Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from the acceptance properties are used instead. Cargo types are from the cargo_type_accept callback, or the accepted_cargo property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|
| cargo_production | (cargo_type * 256) + amount | Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. extra_callback_info1 contains the number of iterations so far, extra_callback_info2 contains random bits.
|
| foundations | CB_RESULT[_NO]_FOUNDATIONS | Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them. |
| autoslope | CB_RESULT[_NO]_AUTOSLOPE | Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it. |
| name | String | Name of the building (when using tile query tool) |
| colour | Palette number |
Used to recolour the building. See here here for an overview of default palettes. |
| construction_check | 0 or 1 | Return 1 to allow building the house or 0 to disallow. |
| destruction | 0 or 1 | Called periodically. Return 0 to keep the building or 1 to destroy it. |
| protection | 0 or 1 | Return 0 to allow destruction, or 1 to disallow |
