Canals/rivers

The code for canals and rivers consists of three parts:

• the canals and rivers' definition
• a 'chain' of performance functions for canals and rivers, considering game-intrinsic variables and including its graphics
• the canals and river's activation

The definition sets the feature properties of a canal or a river ID (slopes, locks, dikes, ..), i.e. its flags and callbacks. Please note that a canal/river definition may only occur after a prior grfinit() function call for the newGRF file.

The canal and river's performance functions are used to group sets of graphics sprites from a previous spriteblock(), or to evaluate game-intrinsic variables, and make both of them accessible to the canal/river's activation function.

The canal and river's activation instantiates the canal/river by finally assigning graphics sets and/or callbacks to a particular canal/river ID. See example below.

Canals and rivers are handled internally as the same feature, with only different IDs used to assign the different graphics to. Therefore, functions definecanal() and makecanal() also handle rivers, not only canals. See here for a list of the usable canal/river IDs.

Function	Meaning
definecanal(<ID>, <block>)	Canal/river definition
makecanal(<ID>, <List::ref()>)	Canal/river activation

This function defines canals/rivers. Its parameters are a fixed ID, and a block of property-defining functions, where the relative position of the property functions is irrelevant. Note that canals/rivers have fixed IDs, in contrast to other features.

Following table lists all IDs together with a description of their associated sprites. Note that the number of sprites might be different for certain IDs, depending on whether flag SPRITEMOD has been set or not:

ID	Description	Sprites	SPRITEMOD
CR_CLIFF	Canal slopes	4 + 1	1 flat ground sprite followed by 4 slope sprites
CR_LOCK	Locks	24	undefined
CR_DIKE	Canal banks	12	undefined
CR_ICON	Icons	1	undefined
CR_DOCK	Flat docks	4	undefined
CR_SLOPE	River slopes	4 + 1	1 flat ground sprite followed by 4 slope sprites
CR_BANK	River banks	12*5 (last 4 for slopes)	undefined
CR_GUI	River GUI	2	undefined

definecanal(CR_SLOPE,
	flags(SPRITEMOD)
	callbacks(CB_OFFS)
)

makecanal(<ID>, <List::ref()>)

This function activates a previously defined canal/river ID. Its parameters are the canal/river ID and a list of references. The number of references given must match the number of consecutive IDs:

makecanal(CR_CLIFF, ref(0))