[MODULE] Mit's AuxiliaryFunctions

[mitlark]

AuxiliaryFunctions
Supported AGS Version: 3.3

Introduction:
A very small contribution to the site, mostly to try out sharing something. It also is a learning experience, since I'm a VERY BAD programmer. VERY. VERY. BAD. And evil.

This little module encapsulates some functions that I've made that I think can be useful for some people.
These functions cover audio playback, scripted colour "picking" and character's screen position instead of room position.

Code Preview:
If anything happens to the download, you can grab the code from here. It's pretty short.

HEADER

Spoiler

Code: ags

// Mit's Auxiliary Functions (MitAF for short)
//============================================
//A bunch of things I found useful to have, and may be useful for others. Or may not.
//This work is done with the hope of giving something to the community. Either as some
//example code or... anything.

/*
DOCUMENTATION
	Usage: Open your project and import this module. Yeah.
	
	Available functions on this module.
	'''''''''''''''''''''''''''''''''''	
	MitAF.rgbToCol(int r, int g, int b)
		Returns a colour number as an integer, based on numerical values given for 
		red (r), green (g) and blue (b).
		Red goes from 0 to 31. Green from 0 to 63. Blue from 0 to 31.
		
	MitAF.playAudio(AudioClip *audio, int repeat)
		  Plays an audio clip. Difference between this and the regular AudioClip.Play() 
		is that this one is meant for more control under channel volume by audio type.
		  It also makes sure replaying a music/ambient sound type doesn't restarts the 
		audio file.
		
	MitAF.playerScreenX()
		Returns the player screen X co-ordinate based on its room X co-ordinate.
		
	MitAF.playerScreenY()
		Returns the player screen Y co-ordinate based on its room Y co-ordinate.
		
	MitAF.characterScreenX (Character *source)
		Returns any character screen X co-ordinate.
		Returns MitAF.playerScreenX() if source character is same as the player.
		
	MitAF.characterScreenY (Character *source)
		Returns source character screen Y co-ordinate.
		Returns MitAF.playerScreenY() if source character is same as the player.
	MitAF.updateAudioChannelVol()
		Updates all channels volume accordingly to their playing audio type.
		You can call this function after changing a volume value (options panel, etc),
		so all playing audio clips reflect the change.
	
	Available static properties (no need of instantiation).
	'''''''''''''''''''''''''''''''''''''''''''''''''''''''
	Mit_ambientChannel
		Pointer to a channel playing ambient sounds. If there has not been played any
		ambient sound at all, it returns null.
	Mit_musicChannel
		Pointer to a channel playing music. If there has not been played any music at 
		all, it returns null.
	Mit_AmbientVolume
		Volume value for Ambient Type audio clips. You can change it at your options panel.
	Mit_MusicVolume
		Volume value for Music Type audio clips. You can change it at your options panel.
	Mit_SFXVolume
		Volume value for SFX Type audio clips. You can change it at your options panel.
*/

// MIT License
// ===========
// (This license it's not mine).

// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.

#define MitAF_VERSION 100 // current version

//For saving channel references.
import AudioChannel *Mit_ambientChannel;
import AudioChannel *Mit_musicChannel;
//Channel volume.
import int Mit_AmbientVolume;
import int Mit_MusicVolume;
import int Mit_SFXVolume;

//Channel volume.
struct MitAF {
	//Available functions.
	import static int rgbToCol(int r, int g, int b);
	import static function playAudio(AudioClip *audio, int repeat);
	import static int playerScreenX();
	import static int playerScreenY();
	import static int characterScreenX (Character *source);
	import static int characterScreenY (Character *source);
	import static function updateAudioChannelVol();
};

[close]

SCRIPT

Spoiler

Code: ags

// Mit's Auxiliary Functions (MitAF for short)
//============================================
//A bunch of things I found useful to have, and may be useful for others. Or may not.
//This work is done with the hope of giving something to the community. Either as some
//example code or... anything.

// MIT License
// ===========
// (This license it's not mine).

// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.

// Available static properties (no need of instantiation).
// '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
// Mit_ambientChannel
// 	Pointer to a channel playing ambient sounds. If there has not been played any
// 	ambient sound at all, it returns null.
AudioChannel *Mit_ambientChannel;
// Mit_musicChannel
// 	Pointer to a channel playing music. If there has not been played any music at 
// 	all, it returns null.
AudioChannel *Mit_musicChannel;

// Mit_AmbientVolume
// 	Volume value for Ambient Type audio clips. You can change it at your options panel.
int Mit_AmbientVolume;
// Mit_MusicVolume
// 	Volume value for Music Type audio clips. You can change it at your options panel.
int Mit_MusicVolume;
// Mit_SFXVolume
// 	Volume value for SFX Type audio clips. You can change it at your options panel.
int Mit_SFXVolume;

//Exports.
export Mit_ambientChannel;
export Mit_musicChannel;
export Mit_AmbientVolume;
export Mit_MusicVolume;
export Mit_SFXVolume;

// MitAF.rgbToCol(int r, int g, int b)
// 		Returns a colour number as an integer, based on numerical values given for 
// 		red (r), green (g) and blue (b).
// 		Red goes from 0 to 31. Green from 0 to 63. Blue from 0 to 31.
static int MitAF::rgbToCol(int r, int g, int b){
	return ( (r*2048)+(g*32)+(b) );
}

// MitAF.playAudio(AudioClip *audio, int repeat)
// 		  Plays an audio clip. Difference between this and the regular AudioClip.Play() 
// 		is that this one is meant for more control under channel volume by audio type.
// 		  It also makes sure replaying a music/ambient sound type doesn't restarts the 
// 		audio file.
static function MitAF::playAudio(AudioClip *audio, int repeat){
	int vol=100;
	AudioChannel *channel;
	if (audio.Type == eAudioTypeAmbientSound) {
		if (Mit_ambientChannel != null){
			if (Mit_ambientChannel.PlayingClip != null) {
				if (Mit_ambientChannel.PlayingClip == audio) return;
			}
		}
		vol = Mit_AmbientVolume;
	}
	else if (audio.Type == eAudioTypeMusic) {
		if (Mit_musicChannel != null){
			if (Mit_musicChannel.PlayingClip != null) {
				if (Mit_musicChannel.PlayingClip == audio) return;
			}
		}
		vol = Mit_MusicVolume;
	}
	else if (audio.Type == eAudioTypeSound) vol = Mit_SFXVolume;
	channel = audio.Play(eAudioPriorityNormal, repeat);
	channel.Volume = vol;
	if (audio.Type == eAudioTypeAmbientSound) Mit_ambientChannel = channel;
	if (audio.Type == eAudioTypeMusic) Mit_musicChannel = channel;
}

// MitAF.playerScreenX()
// 		Returns the player screen X co-ordinate based on its room X co-ordinate.
static int MitAF::playerScreenX(){
	int sHalf = (System.ScreenWidth/2);
	int rX = Room.Width - sHalf;
	if (player.x <= sHalf) return player.x;
	if (player.x > rX) return (player.x - (rX-sHalf));
	return sHalf;
}

// MitAF.playerScreenY()
// 		Returns the player screen Y co-ordinate based on its room Y co-ordinate.
static int MitAF::playerScreenY(){
	int sHalf = (System.ScreenHeight/2);
	int rY = Room.Height - sHalf;
	if (player.y <= sHalf) return player.y;
	if (player.y > rY) return (player.y - (rY-sHalf));
	return sHalf;
}

// MitAF.characterScreenX (Character *source)
// 		Returns any character screen X co-ordinate.
// 		Returns MitAF.playerScreenX() if source character is same as the player.
static int MitAF::characterScreenX (Character *source){
	int pSX = MitAF.playerScreenX();
	if (source.ID==player.ID) return pSX;
	return ( (source.x - player.x) + pSX );
}

// MitAF.characterScreenY (Character *source)
// 		Returns any character screen Y co-ordinate.
// 		Returns MitAF.playerScreenY() if source character is same as the player.
static int MitAF::characterScreenY (Character *source){
	int pSY = MitAF.playerScreenY();
	if (source.ID==player.ID) return pSY;
	return ( (source.y - player.y) + pSY );
}

// MitAF.updateAudioChannelVol()
// 		Updates all channels volume accordingly to their playing audio type.
// 		You can call this function after changing a volume value (options panel, etc),
// 		so all playing audio clips reflect the change.
static function MitAF::updateAudioChannelVol(){
	int i=0;
	int vol=100;
	AudioClip *audio;
	AudioChannel *channel;
	
	while (i<System.AudioChannelCount){
		channel = System.AudioChannels[i];
		audio = channel.PlayingClip;
		if (audio != null) {
			if (audio.Type==eAudioTypeAmbientSound) vol=Mit_AmbientVolume;
			else if (audio.Type==eAudioTypeMusic) vol=Mit_MusicVolume;
			else if (audio.Type==eAudioTypeSound) vol=Mit_SFXVolume;
			channel.Volume = vol;
		}
		i++;
	}
}

[close]

Module download:
- Download link -

SPECIAL THANKS
To whoever wrote the manual <3. And to the community, for this extensive experience database known as forum.

[Monsieur OUXX]

thanks mit