Version 0.17.0

Yes, ladies, gentlemen and others, the pink engine is not dead. The new version took longer to put together than I had expected, due to having to work around certain restrictions in ren'py in a rather creative way. 

This update, which I'm unofficially calling 'the sound update 2.0', focuses on adding more sound-related functionality to the game. It is specifically focused on two sound features: Movement sounds and Locational sounds. 

Movement Sounds: A quick overview

Movement sounds are your classic 'walk over a tile to make a noise' sounds. They are defined by attaching a sound_tag property to an object or tile, and then coupling that sound_tag to a a sound file in the pink_otm_terrain_noises dictionary (located in standard_events.rpy). The test maps contain three tiles with attached sounds. 

By default, only the player and followers make movement sounds, but it's possible to make NPCs make movement sounds as well through the movement_sound_function property. You can set this to 'pink_movement_sound_terrain' to use the same movement sound logic as the player. However, you can also make it so that an NPC plays the same sound effect on every movement, by setting movement_sound_function to 'pink_movement_sound_static' and set the new property movement_sound to point to the filepath for the sound effect you want. This is nice for big stompy robots and such. You can also set a movement_sound_blocked property on any object, no matter which function you are using, pointing to a sound effect to play on an unsuccesful move. 

The functions pink_movement_sound_terrain and pink_movement_sound_static are both defined in standard_events.rpy, and you can alter these functions, or add your own if you want. A tester on the discord server made it so that a particular followers would play a special sound effect when walking over a particular tile. 

Locational Sounds: A quick overview

Locational sounds are sounds that change in volume and panning depending on the distance between the location from which the sound is being emitted, and the current camera target (usually the player character). There's currently three ways to trigger locational sounds:

First, the ControlCommand class has been extended to allow any movement function that can create a sound effect have that sound effect be locational. You do this by setting the scale_sound and/or pan_sound arguments to True when creating the control command.

Secondly, you can call pink.otm.play_locational_sound during an event to play a sound effect at a specified location.

Third, there is the new emits_sound property, which when set causes an object to play a sound effect on a constant, consistent loop. This is useful for environmental sounds, such as rushing fountains, blowing winds, loud annoying engines, etc. 

Locational sounds are extremely configurable. All three options for playing locational sounds allow you to only pan or only scale, set the maximum and minimum volume, set the distances at which these occur, set the maximum pan, the distance at which the maximum pan is achieved and the distance up to which there is no panning at all. You can even set the mixer for locational sounds, allowing the volume to be derived from either the 'sfx', 'music' or 'voice' slider in the settings. See the documentation for the exact properties, arguments and attributes that come into play for each of the three methods.

Other changes

In addition to the core changes related to movement and locational sound, a number of minor changes was made as well. 

Users rightfully stated that having to specify never_repeat=True on control commands for every single non-looping control command was a major source of frustration. As such, I've now made it so that when an event is currently running, the ControlCommand class will assume that any control command is supposed to never repeat, and you'll only need to specify it in the rare cases where you want it to repeat. If you want to disable this functionality for the sake of compatibility, you can set default_never_repeat_during_event in pink_config.rpy to False. 

There were also issues with the pink console, where games that had a really high resolution would have unreadably small text in the console. As such, I've made the text size in the pink console configurable using the new pink_console_text_size variable in pink_config.rpy. 

There was some complaints in regards to some NPCs having an awkward delay in regards to turning to the player when interacted with if those NPCs had a movement cycle that had "delay" or any variety of "turn" right as they were interacted with. To deal with these cases, as well as providing a handy way of just cutting off movement during event when neccesary, the .interrupt() function was added to objects. Interrupt causes an object to instantly complete its current movement. You can also set the interrupt_on_interaction property on an object so that any interaction with them will cause an interrupt. Be warned that interrupting a moving NPC will cause them to instantly teleport to their finale location, so this might not be suitable for all your NPCs. 

Documentation

This is an overview of all new functions, attributes, and arguments added to the pink engine in this version. 

New config options

• pink_console_text_size - The text size to be used in the pink console
• default_never_repeat_during_event - When True, makes it so that never_repeat will default to True when creating a ControlCommand during an event, False in other cases. When False, never_repeat will always default to False.
• pink_otm_default_min_volume_distance - The default distance at which a locational sound effect will achieve its minimum volume.
• pink_otm_default_max_pan_distance - The default distance at which a locational sound effect will achieve its maximum panning
• pink_player_default_movement_sound_function - The sound function that the player should use. This should be the name of a function in the ren'py store. By default, the pink engine contains the functions 'pink_movement_sound_terrain' and 'pink_movement_sound_static', which are suitable movement functions, but you can define your own if you want to.
• pink_follower_default_movement_sound_function - The sound function that followers should use by default. 
• pink_player_default_movement_sound - If the player's movement function is set to 'pink_movement_sound_static', this is the sound effect that plays on every movement. 
• pink_follower_default_movement_sound - If a follower's movement function is set to 'pink_movement_sound_static', this is the sound effect that plays on every movement unless that follower has a different specified sound
• pink_player_default_movement_sound_blocked - The filepath to the sound effect that should play if the player attempts an impossible move. Set to None if you don't want to have such a move. 
• pink_otm_default_npc_movement_sound_multiplier - The volume multiplier on movement sound effects for NPCs. If you've got lots of tightly packed NPCs in your maps, you're gonna want a low volume for this. Note that you can change this value for individual NPCs, this is just hte default value. 
• pink_otm_default_no_movement_volume_distance - The distance at which movement volume should no longer be audible. This too can be adjusted for individual NPCs.
• pink_otm_default_follower_movement_sound_multiplier - The volume multiplier on movement sound effects for your followers. 

New object/tile property related to movement sound

• sound_tag (str) - The tag for movement sound played when moving into this object. Note that the tag should correspond to a key in the pink_otm_terrain_noises dictionary defined in standard_events.rpy. Defaults to None, resulting in no movement sound happening.

New object properties related to movement sound:

• movement_sound_function (str) - The name of the function that should be used to play movement sounds for this character. The default valid values for this are 'pink_movement_sound_terrain' and 'pink_movement_sound_static', which are defined in standard_events.rpy. You can define your own functions for this as well, though they need the same signature as the existing movement sound functions. When set to 'pink_movement_sound_terrain', the moving character will play a movement sound that depends on the terrain underneath them, looking at the sound_tag value of underlying terrain and looking up the tag in the pink_otm_terrain_noises dictionary to find the corresponding file. When set to 'pink_movement_sound_static', the moving character will always play the same sound on moving, which is the value of the movement_sound attribute. Defaults to None, which means it doesn't make any movement sound.
• movement_sound_blocked (str) - The filepath for the sound effect to play for unsuccessful movement. More plainly speaking, the sound effect to play when you bump into walls. Defaults to None, which causes no sound effect to play.
• movement_sound (str) - The filepath for the sound effect to play for successful movement. Only has an effect for objects with the movement sound function 'pink_movement_sound_static'.
• movement_sound_multiplier (float) - Multiplies the volume of the movement sound effects by the given value. Defaults to the value of pink_otm_default_npc_movement_sound_multiplier for most objects, pink_otm_default_follower_movement_sound_multiplier for followers, and 1.0 for the player character.
• movement_sound_max_distance (int) - The maximum distance in tiles at which you can hear movement sounds from this object. Defaults to pink_otm_default_no_movement_volume_distance .

Arguments for instantiating a ControlCommand with locational sound effects

• scale_sound (bool) - Whether the sound is scaled with distance. Defaults to False.
• max_volume_distance (int) - The distance in tiles up to which the sound will play at maximum volume. Defaults to 1.
• min_volume_distance (int) - The distance in tiles from which the sound will play at the minimum volume. Defaults to the value of pink_otm_default_min_volume_distance.
• min_volume (float) - Minimum volume to which sound scaling can reduce the sound. Defaults to 0.0.
• max_volume (float) - Maximum volume to which sound scaling can increase the sound. Defaults to 1.0.
• pan_sound (bool) - Whether the sound effect should pan with horizontal distance. Defaults to False.
• max_pan_distance (int) - The distance in tiles from which the sound will play fully panned. Defaults to pink_otm_default_max_pan_distance.
• no_pan_distance (int) - The distance in tiles up to which the sound object will not pan. Defaults to 0
• max_pan (float) - The absolute maximum level of panning that can be achieved by changing position relative to the emitting object. Note that this sets the value for both the maximum left pan and right pan. Defaults to 1.0, which is sound only emitting from a single box.
• mixer (str) - Which sound mixer (sound slider in the settings) should be used to control the volume of the sound. This only valid options are the default mixers of 'sfx', 'music' and 'voice', with no built-in support for custom mixers. Defaults to 'sfx', which is the sound slider.

New optional arguments for function pink.otm.add_player_follower:

• movement_sound_function (str) - Sets the movement_sound_function property for the follower. Defaults to pink_follower_default_movement_sound_function.
• movement_sound (str) - Sets the movement_sound property for the follower. Defaults to pink_follower_default_movement_sound
• movement_sound_multiplier (float) - Sets the movement_sound_multiplier for the follower. Defaults to pink_otm_default_follower_movement_sound_multiplier

Arguments for pink.otm.play_locational_sound (only path, x_coord and y_coord are mandatory)

• path (str) - The filepath to the sound effect that should be played. Filepath should be relative to the /game/ folder. 
• x_coord (int) - The x coordinate that the sound should emanate from
• y_coord (int) - The y coordinate that the sound should emanate from
• scale_sound (bool) - Whether the sound is scaled with distance. Defaults to True.
• max_volume_distance (int) - The distance in tiles up to which the sound will play at maximum volume. Defaults to 1.
• min_volume_distance (int) - The distance in tiles from which the sound will play at the minimum volume. Defaults to the value of pink_otm_default_min_volume_distance.
• min_volume (float) - Minimum volume to which sound scaling can reduce the sound. Defaults to 0.0.
• max_volume (float) - Maximum volume to which sound scaling can increase the sound. Defaults to 1.0.
• pan_sound (bool) - Whether the sound effect should pan with horizontal distance. Defaults to True.
• max_pan_distance (int) - The distance in tiles from which the sound will play fully panned. Defaults to pink_otm_default_max_pan_distance.
• no_pan_distance (int) - The distance in tiles up to which the sound object will not pan. Defaults to 0
• max_pan (float) - The absolute maximum level of panning that can be achieved by changing position relative to the emitting object. Note that this sets the value for both the maximum left pan and right pan. Defaults to 1.0, which is sound only emitting from a single box.
• mixer (str) - Which sound mixer (sound slider in the settings) should be used to control the volume of the sound. This only valid options are the default mixers of 'sfx', 'music' and 'voice', with no built-in support for custom mixers. Defaults to 'sfx', which is the sound slider.

New object properties related to emits_sounds

• emits_sound (str) - Path to the sound effect getting emitted. Defaults to None, resulting in no sound getting emitted.
• emits_sound_scale (bool) - Whether the emitted sound is scaled with distance. Defaults to True.
• emits_sound_min_volume (float) - Minimum volume to which sound scaling can reduce the sound. If at any level other than 0.0, this means that the sound can be heard from anywhere in the map. Defaults to 0.0, which is 0% volume.
• emits_sound_max_volume (float) - Maximum volume to which sound scaling can increase the sound. Defaults to 1.0, which is 100% volume.
• emits_sound_min_volume_distance (int) - The distance in tiles from which the emitted sound from this object will play at the minimum volume. If not set, defaults to the value of pink_otm_default_range_for_min_volume.
• emits_sound_max_volume_distance (int) - The distance in tiles up to which the emitted sound from this object will play at maximum volume. Defaults to 1.
• emits_sound_pan (bool) - Whether the sound effect emanating from this object should pan with horizontal distance. Defaults to True.
• emits_sound_max_pan (float) - The absolute maximum level of panning that can be achieved by changing position relative to the emitting object. Note that this sets the value for both the maximum left pan and right pan. Defaults to 1.0, which is 100% panning.
• emits_sound_mixer (str) - Which sound mixer (sound slider in the settings) should be used to control the volume of the sound emanating from this object. This only valid options are the default mixers of 'sfx', 'music' and 'voice', with no built-in support for custom mixers. Defaults to 'sfx' (the sound slider).
• emits_sound_max_pan_distance (int) - The distance in tiles from which the emitted sound from this object will play fully panned. Defaults to the value of pink_otm_default_range_for_max_pan
• emits_sound_no_pan_distance (int) - The distance in tiles up to which emitted sound from this object will not pan. Defaults to 0.

New functions on objects:

• interrupt() - Instantly finishes executing the current ongoing command, meant for usage during events.

Other new object properties

• interrupt_on_interaction (bool) - Causes a character to call the interrupt function on themselves when interacted with, instantly finishing their current movement. Meant for uses where an NPC has delays or turns as part of their movement routine, which would otherwise delay turning to face the player.

Test Rooms

• Test Room B20 - This test room has been updated so that all special movement sound effects are locational
• Test Room E24 - This new room tests the new emits_sound function. It has a single object in its center, which has the emits_sound property. Interacting with this object allows you to alter the various emits_sound-related properties on that object. 
• Test Room E25 - This new room tests having multiple sound-emitting objects in the same room. There is a total of three objects with emits_sound in this room, and you should hear the volume and panning shift around as you wander the room.
• Test Room E26 - This new room tests mobile sound-emitting object. Emits_sound has been added to a single moving NPC, which wanders around the room on a set track.
• Test Room E27 - This new room tests locational sounds emitted through ControlCommands. It has the same NPC following a track as room E26, but rather than having a emits_sound property, it uses a play_sound control command whenever it turns. 
• Test Room E28 - This new room tests movement sounds, with the various new tiles in this room having a sound_tag property that should cause sound effects to play as you or your followers walk over them. There is also a computer in this room that you can interact with to set movement_sound_blocked on the player character, making a weird bass-y noise as you bump into walls.
• Test Room E29 - This new room demonstrates a long-present but never documented feature of the pink engine: The ability to have maps that make use of non-square tiles.