ActionF

From GRFSpecs
Revision as of 16:40, 7 September 2005 by dmccoy (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Define new town name styles

Action F - Town names

Define new town name styles

-=Introduction=-

This action can be used to define new town name styles for random games and random cities placed in the scenario editor.

-=Format=-

The data looks as follows:

 -+<Sprite-number> * <Length> 0F <ID> <stylenames> <num-parts> <parts>...+-

||Element|Size|Description

<Sprite-number>|dec|A sequential sprite number

<length>|dec|The total number of bytes used in this action.

<ID>|B|    ID of this definition in the bottom 7 bits. If bit 7 is set, this is a final definition (it will be displayed in the Options window), if it's clear, this is an intermediate definition that can be used to create more complex decision chains, see below. Final and intermediate definitions share the same 128 IDs, so 01h and 81h define the same ID for different usages, and not two separate IDs.

<style-names>|V|This is only present in final definitions, see below for the format

<num-parts>|B|How many parts this name is put together from.

<parts>|V|Data about the various parts, see below||

Style names

This item is only present if bit 7 is set in the ID.  Its contents are in the format:

 -+<nowiki>[<langs> <name>]</nowiki>... 00+-

||Element|Size|Meaning

langs|B|Bit mask of languages in which the following style name can be displayed. It's in the same format as for action 4, except that bit 7 is ignored.

name|S|Null-terminated style name to be displayed in the Options window.||

This can be repeated as often as necessary, then a literal "00" terminates the style name definition. If no appliable name is found, "(unnamed style)" will be displayed in the Options window.

Parts

The following fields are repeated for every part (num-parts times):

 -+ <textcount> <firstbit> <bitcount> <nowiki>[ <probablity> <part/ID> ]</nowiki>... +-

||Element|Size|Meaning

textcount|B|The number of possible values for this part

firstbit|B|Number of the lowest bit that counts for determining the value of the part

bitcount|B|How many bits are used for determining the value of this part||

Every town has 32 random bits for random naming. You can use the <firstbit> field to make the decisions for every part linearly independent, or at least as independent as possible.

The minimal number for the <bitcount> field should be the lowest power of 2 that is higher than the sum of all probabilities (e.g. 2 if the sum is <=4, 3 if it's <=8, 4 if <=16 and so on), but allowing more bits can make the distribution of decisions smoother.

The following fields are repeated for every text (textcount times) in every part:

||Element|Size|Meaning

probablity|B|The relative probablity of the following name to appear in the bottom 7 bits. Bit 7 decides the meaning of the following field.

part|S|If bit 7 of probablity is clear, the following field is a null-terminated string containing a name part itself. This can be an empty string (just a plain zero byte) to avoid generating this part. (This can be useful for an optional part: give a high probablity to an empty part to appear, and low probablities to many non-empty parts, so you effectively decrease the chance that the part appears at all)

ID|B|If bit 7 of the probablity is set, the following byte is an ID for an intermediate action F. The random name defined by the given ID is generated, then inserted into the current name as a name part. Specifying an ID that isn't defined yet results in an error and therefore disabling all town name definitions in the file.||

-=Notes=-

That town name styles are special since they have to be available on the title screen as well, where the graphics files aren't activated yet. This means they're processed at the initialization stage only, and can be skipped only by action 9, but doing so will prevent them from working for the rest of the game. The only way to disable a new town name style once it's loaded is to disable the entire GRF file it's situated in (by using the "New GRF status" window or by putting an exclamation mark next to the filename in newgrf(w).txt).

A town name generated this way must meet some requirements to be accepted by TTD: it can't be empty (so you don't have to worry even if your chain can generate an empty string), can't be a name that's already given to a town (to avoid duplicate town names),  can't be longer than 31 characters and its displayed form can't be wider than 130 pixels. If a generated name doesn't meet all these requirements, TTD tries again with a different random value. For this reason, your town name style must be able to generate at least 70 different acceptable combinations, since this is the maximum number of towns possible on a map, and TTD may deadlock if it can't find different names for every town on the map.

The town name style dropdown menu doesn't support more than 19 entries, and since six entries are already reserved for the old styles, only 13 remain for new styles. If there are more than 13 final style definitions available, only the first 13 will be displayed in the dropdown menu, and therefore be selectable. The other definitions will still be available (e.g. they'll show up in games started with them), but cannot be selected from the user interface.

If your GRF isn't available while its name style definition is used in a savegame, the town name style reverts back to German, but the towns get both English and German names; they appear in the wrong order in the town list and duplicate town names may appear. However, no data loss occurs, so the correct names are restored as soon as your definition becomes available again.

-=Example=-

...