Arkos 1.0 integration by Greenweb

README.md

@@ -38,6 +38,8 @@ Por nuestra parte es posible que el motor sólo reciba correcciones, pero los _p
 * Compresor para aplib [apultra](https://github.com/emmanuel-marty/apultra) por **Emmanuel Marty**.
 * WYZ Player por WYZ, modificado por **na_th_an** (compresión) y **thEpOpE** (FX con ruido).
 * WYZ Tracker 0.5.0.2 por **Augusto Ruiz**.
+* ARKOS Player 1.0 por **Targhan/Grim/Arkos**.
+* Integración con ARKOS por **Greenweb** basada en el trabajo de **Syx**.
 * ROM-based tape loader y Gentape por **Antonio Villena**.
 * **bas2tap** por **Martijn Van Der Heide**.
 * **bin2tap** por **mike/zeroteam**.

docs/README.md

@@ -21,6 +21,11 @@ En este directorio está disponible la documentación existente sobre **MTE MK1*
 * [Capítulo 15: Custom Vertical Engine](./tutorial-cap15.md)
 * [Capítulo 16: Más de 16 gráficos para *sprites*](./tutorial-cap16.md)
 
+## Contrdibuciones
+
+* [Manual FX para MK2 con WYZ](./contribs/Manual%20FX%20para%20MK2%20con%20WYZ.pdf) por **Greenweb**.
+* [Manual para música Arkos 1.0](./contribs/arkos.md) por **Greenweb**.
+
 ## Referencias
 
 * [API de **MTE MK1**](./API.md)

docs/contribs/arkos.md

@@ -0,0 +1,125 @@
+# Uso de Arkos Player en juegos 128k
+
+Ahora en juegos de 128k podemos usar para crear músicas y efectos de sonidos (SFX) tanto **Wyz Tracker** como **Arkos Tracker 1**.
+
+El proceso de añadir músicas en **Arkos** era algo más complejo que en Wyz ya que las canciones hay que compilarlas en la dirección de memoria en la que van a ser guardadas, por lo que era algo más laborioso sobre todo si estás en fase de pruebas.
+
+Gracias a una utilidad de **MTE MK1**, ahora el proceso es mucho más automático y tan solo hay que preparar en juego para usarlo en unos sencillos pasos que detallaremos ahora.
+
+## Activando Arkos Player
+
+Lo primero es tener tu juego montado para 128k, claro. El sonido que usa Arkos es el que el chip AY produce, por tanto solo es válido para modelos 128k.
+
+Para eso puedes leer en la doc (si, hay una carpeta "docs" llena de informacion) el * [Capítulo 13: Un juego de 128K](./tutorial-cap13.md), pero si tu juego no va a usar multi niveles y solo quieres música 128k, te lo ponemos aún más fácil. Sigue leyendo.
+
+Abre el archivo `config.h` y verás que justo al inicio, hay 3 líneas tal que así:
+
+```c
+	// #define MODE_128K 						// Read the docs!
+	// #define USE_ARKOS_PLAYER					// Use Arkos instead of Wyz player for 128k Music
+	// #define ARKOS_SFX_CHANNEL	0			// SFX Channel (0-2)
+```
+
+Si descomentamos la primera línea, activaremos toda la mandanga de 128k, incluyendo el sonido y el Wyz Player. Si queremos usar Arkos en lugar de Wyz, tendremos que descomentar las dos líneas siguientes, y elegir el canal porque el que sonarán los sonidos FX en la tercera línea. Sobre eso tu músico te dirá cual es el adecuado, o debería decírtelo.
+
+Perfecto, ahora que tenemos el 128k activado, vamos a probar el juego demo, que por defecto trae unas musiquillas listas para compilar.
+
+## Preparando `compile.bat`
+
+Vamos a abrir ahora el archivo "compile.bat" para prepararlo según nuestra elección. Aquí hay varias cosas que ver. Vamos por partes:
+
+### Librarian
+
+Hay que activar el librarian, que es una utilidad que se encarga de ordenar los trastos que van en toda la RAM extra del 128k, incluida la música y las pantallas fijas como el menú, marco y la pantalla del final. Busca estas líneas y mira que no estén comentadas:
+
+```bat
+	echo Running The Librarian
+	..\utils\librarian2.exe list=..\bin\list.txt index=assets\librarian.h bins_prefix=..\bin\ rams_prefix=..\bin\ > nul
+```
+
+### Conversiones
+
+A continuación veremos el bloque "Música AY". Aqui tenemos que descomentar la parte del player que vayamos a usar, para usar Arkos quedaría así:
+
+```bat
+	rem *** Música AY: Descomenta el player que vayas a usar (Wyz o Arkos) ***
+
+	rem echo Compilando musica 128k - Wyz Player
+	rem cd ..\mus
+	rem ..\utils\apultra.exe menu.mus menu.bin
+	rem ..\utils\apultra.exe level1.mus level1.bin
+	rem ..\utils\pasmo WYZproPlay47aZXc.ASM ..\bin\RAM1.bin 
+	rem cd ..\dev
+
+	echo Compilando musica 128k - Arkos Player
+	cd ..\mus_arkos
+	if [%1]==[nomus] goto :nomus
+	..\utils\build_mus_bin.exe ram1.bin > nul
+	:nomus
+	copy ram1.bin ..\bin
+	copy arkos-addresses.h ..\dev\sound
+	cd ..\dev	
+```
+
+### Seleccionando cargador
+
+Por último veremos más abajo el bloque "Tipo de cargador" donde tenemos que comentar el cargador para 48k y descomentar el de 128k. Quedaría así:
+
+```bat
+	rem *** Tipo de cargador ***
+
+	rem echo Construyendo cinta 48k
+	rem cambia LOADER por el nombre que quieres que salga en Program:
+	rem ..\utils\bas2tap -a10 -sLOADER loader\loader.bas loader.tap > nul
+	rem ..\utils\bin2tap -o screen.tap -a 16384 loading.bin > nul
+	rem ..\utils\bin2tap -o main.tap -a 24000 %game%.bin > nul
+	rem copy /b loader.tap + screen.tap + main.tap %game%.tap > nul
+
+	echo Construyendo cinta 128k
+	..\utils\imanol.exe ^
+		in=loader\loaderzx.asm-orig ^
+		out=loader\loader.asm ^
+		ram1_length=?..\bin\RAM1.bin ^
+		ram3_length=?..\bin\RAM3.bin ^
+		mb_length=?%game%.bin  > nul
+
+	..\utils\pasmo.exe loader\loader.asm ..\bin\loader.bin loader.txt
+
+	rem cambia LOADER por el nombre que quieres que salga en Program:
+	..\utils\GenTape.exe %game%.tap ^
+		basic 'LOADER' 10 ..\bin\loader.bin ^
+		data                loading.bin ^
+		data                ..\bin\RAM1.bin ^
+		data                ..\bin\RAM3.bin ^
+		data                %game%.bin
+```
+
+### Compilando 
+
+¡LISTO! Ahora si compilamos el juego demo debería sonar música y SFX usando el Arkos Player (o Wyz si elegiste este otro). Pero éstas son solo unas músicas de ejemplo para comprobar que todo va bien. Veamos ahora como cambiar las canciones y SFX por los tuyos propios.
+
+## Tu propia mandanga
+
+Entiendo que estás usando Arkos, así que nos centraremos en este player. Vete a la carpeta "mus_arkos" y vas a encontrar uno cuantos archivos. 
+
+Los archivos .aks son las canciones que exporta el Arkos Tracker y una de ellas contiene exclusivamente los SFX. Puedes abrirlos con el tracker y ver como están hechos.
+
+Cuando tengas tus propias canciones y SFX hechos, tendrás que editar el archivo `song_list.txt` que está en esta misma carpeta. Este archivo contiene la lista de canciones en el orden en que serán compiladas y guardadas en memoria. Si abres el archivo verás esto:
+
+```
+	Cancion_00.aks
+	Cancion_01.aks
+	Cancion_02.aks
+	Cancion_03.aks
+	sfx.aks<
+```
+
+El ultimo es el fichero con los SFX y para indicarlo ponemos el signo < justo despues de su nombre. Como ves, la primera cancion es la 0, la segunda la 1, etc. Así se le deben llamar desde el juego. En el juego demo "Lala Prologue" la música que suena en el menú es la 0 y se llama desde esta funcion que encontrarás en "my/title_screen.h" si tienes curiosidad o simplemente quieres cambiarla por otra:
+
+```c
+	PLAY_MUSIC (0);
+```
+
+Pues bien, edita este archivo `song_list.txt` y pon tu lista de canciones y SFX. Solo eso, guardas los cambios y al compilar tu juego de nuevo ya deberían sonar las nuevas melodías y efectos de sonido. Si no va bien, repasa todo.
+
+Recuerda tambien que en **MTE MK1**, en la carpeta `/dev/assets/`, hay un archivo llamado `ay_fx_numbers.h` donde puedes asignar que SFX sonará con cada acción del juego (salto, disparo, recibir daño, etc). ¡OJO! Los SFX en Arkos se numeran del 1 en adelante, a diferencia de con Wyz que empiezan en el cero.

src/dev/assets/ay_fx_numbers.h

@@ -1,20 +1,42 @@
 // MTE MK1 (la Churrera) v5.0
 // Copyleft 2010-2014, 2020 by the Mojon Twins
 
-#define SFX_START 				0
-#define SFX_BREAKABLE_HIT 		1
-#define SFX_BREAKABLE_BREAK 	2
-#define SFX_PUSH_BOX 			3
-#define SFX_OPEN_LOCK 			3
-#define SFX_SHOOT 				4
-#define SFX_OBJECT_GET 			5
-#define SFX_KILL_ENEMY_STEP 	6
-#define SFX_KILL_ENEMY_SHOOT	6
-#define SFX_HIT_ENEMY 			7
-#define SFX_ONE_OBJECT_GET		8
-#define SFX_ONE_OBJECT_WRONG 	9
-#define SFX_KEY_GET 			10
-#define SFX_REFILL_GET 			11
-#define SFX_JUMP 				12
-#define SFX_SPIKES 				13
-#define SFX_ENEMY_HIT 			14
+#ifdef USE_ARKOS_PLAYER
+	#define SFX_START 				1
+	#define SFX_BREAKABLE_HIT 		1
+	#define SFX_BREAKABLE_BREAK 	2
+	#define SFX_PUSH_BOX 			3
+	#define SFX_OPEN_LOCK 			3
+	#define SFX_SHOOT 				4
+	#define SFX_OBJECT_GET 			5
+	#define SFX_KILL_ENEMY_STEP 	6
+	#define SFX_KILL_ENEMY_SHOOT	6
+	#define SFX_HIT_ENEMY 			7
+	#define SFX_ONE_OBJECT_GET		8
+	#define SFX_ONE_OBJECT_WRONG 	9
+	#define SFX_KEY_GET 			4
+	#define SFX_REFILL_GET 			11
+	#define SFX_JUMP 				2
+	#define SFX_SPIKES 				2
+	#define SFX_ENEMY_HIT 			8
+
+#else
+	#define SFX_START 				0
+	#define SFX_BREAKABLE_HIT 		1
+	#define SFX_BREAKABLE_BREAK 	2
+	#define SFX_PUSH_BOX 			3
+	#define SFX_OPEN_LOCK 			3
+	#define SFX_SHOOT 				4
+	#define SFX_OBJECT_GET 			5
+	#define SFX_KILL_ENEMY_STEP 	6
+	#define SFX_KILL_ENEMY_SHOOT	6
+	#define SFX_HIT_ENEMY 			7
+	#define SFX_ONE_OBJECT_GET		8
+	#define SFX_ONE_OBJECT_WRONG 	9
+	#define SFX_KEY_GET 			10
+	#define SFX_REFILL_GET 			11
+	#define SFX_JUMP 				12
+	#define SFX_SPIKES 				13
+	#define SFX_ENEMY_HIT 			14
+
+#endif

src/dev/compile.bat

@@ -37,24 +37,64 @@ echo Importando GFX
 ..\utils\png2scr.exe ..\gfx\marco.png ..\gfx\marco.scr > nul
 ..\utils\png2scr.exe ..\gfx\ending.png ..\gfx\ending.scr > nul
 ..\utils\png2scr.exe ..\gfx\loading.png loading.bin > nul
-..\utils\apultra.exe ..\gfx\title.scr title.bin > nul
-..\utils\apultra.exe ..\gfx\marco.scr marco.bin > nul
-..\utils\apultra.exe ..\gfx\ending.scr ending.bin > nul
+..\utils\apultra.exe ..\gfx\title.scr ..\bin\title.bin > nul
+..\utils\apultra.exe ..\gfx\marco.scr ..\bin\marco.bin > nul
+..\utils\apultra.exe ..\gfx\ending.scr ..\bin\ending.bin > nul
 
 if [%1]==[justassets] goto :end
 
+rem echo Running The Librarian
+rem ..\utils\librarian2.exe list=..\bin\list.txt index=assets\librarian.h bins_prefix=..\bin\ rams_prefix=..\bin\ > nul
+
+rem *** Música AY: Descomenta el player que vayas a usar (Wyz o Arkos) ***
+
+rem echo Compilando musica 128k - Wyz Player
+rem cd ..\mus
+rem ..\utils\apultra.exe menu.mus menu.bin
+rem ..\utils\apultra.exe level1.mus level1.bin
+rem ..\utils\pasmo WYZproPlay47aZXc.ASM ..\bin\RAM1.bin 
+rem cd ..\dev
+
+rem echo Compilando musica 128k - Arkos Player
+rem cd ..\mus_arkos
+rem if [%1]==[nomus] goto :nomus
+rem ..\utils\build_mus_bin.exe ram1.bin > nul
+rem :nomus
+rem copy ram1.bin ..\bin
+rem copy arkos-addresses.h ..\dev\sound
+rem cd ..\dev
+
 :compile
 echo Compilando guego
 zcc +zx -vn mk1.c -o %game%.bin -lsplib2_mk2.lib -zorg=24000 > nul
 ..\utils\printsize.exe %game%.bin
 ..\utils\printsize.exe scripts.bin
 
+rem *** Tipo de cargador ***
+
 echo Construyendo cinta
 rem cambia LOADER por el nombre que quieres que salga en Program:
 ..\utils\bas2tap -a10 -sLOADER loader\loader.bas loader.tap > nul
 ..\utils\bin2tap -o screen.tap -a 16384 loading.bin > nul
 ..\utils\bin2tap -o main.tap -a 24000 %game%.bin > nul
 copy /b loader.tap + screen.tap + main.tap %game%.tap > nul
+rem echo Construyendo cinta 128k
+rem ..\utils\imanol.exe ^
+rem in=loader\loaderzx.asm-orig ^
+rem out=loader\loader.asm ^
+rem ram1_length=?..\bin\RAM1.bin ^
+rem ram3_length=?..\bin\RAM3.bin ^
+rem mb_length=?%game%.bin  > nul
+
+rem ..\utils\pasmo.exe loader\loader.asm ..\bin\loader.bin loader.txt
+
+rem cambia LOADER por el nombre que quieres que salga en Program:
+rem ..\utils\GenTape.exe %game%.tap ^
+rem basic 'LOADER' 10 ..\bin\loader.bin ^
+rem data                loading.bin ^
+rem data                ..\bin\RAM1.bin ^
+rem data                ..\bin\RAM3.bin ^
+rem data                %game%.bin
 
 if [%1]==[justcompile] goto :end
 if [%1]==[noclean] goto :end

src/dev/engine.h

@@ -153,7 +153,7 @@ void espera_activa (int espera) {
 
 					// Sonido
 					#ifdef MODE_128K
-						wyz_play_sound (SFX_PUSH_BOX);
+						PLAY_SOUND (SFX_PUSH_BOX);
 					#else			
 						beep_fx (2);	
 					#endif
@@ -182,7 +182,7 @@ void espera_activa (int espera) {
 				-- p_keys;
 
 				#ifdef MODE_128K
-					wyz_play_sound (SFX_OPEN_LOCK);
+					PLAY_SOUND (SFX_OPEN_LOCK);
 				#else
 					beep_fx (8);
 				#endif
@@ -624,7 +624,8 @@ void select_joyfunc (void) {
 	}
 
 	#ifdef MODE_128K
-		wyz_play_sound (SFX_START);
+		STOP_SOUND ();
+		PLAY_SOUND (SFX_START);
 		sp_WaitForNoKey ();
 	#endif
 }

src/dev/engine/breakable.h

@@ -23,7 +23,7 @@ void break_wall (void) {
 		#include "my/ci/on_wall_broken.h"
 	}
 	#ifdef MODE_128K
-		wyz_play_sound (gpit);
+		PLAY_SOUND (gpit);
 	#else			
 		// Show what just happened before the sound interrupts the action
 		sp_UpdateNow ();

src/dev/engine/bullets.h

@@ -166,7 +166,7 @@ void bullets_fire (void) {
 			#endif
 
 			#ifdef MODE_128K
-				wyz_play_sound (SFX_SHOOT);
+				PLAY_SOUND (SFX_SHOOT);
 			#else
 				beep_fx (6);
 			#endif

src/dev/engine/enengine.h

@@ -450,7 +450,7 @@ void enems_move (void) {
 						#endif				
 						{
 							#ifdef MODE_128K
-								wyz_play_sound (SFX_KILL_ENEMY_STEP);										
+								PLAY_SOUND (SFX_KILL_ENEMY_STEP);										
 								en_an_state [enit] = GENERAL_DYING;
 								en_an_count [enit] = 12;
 								en_an_next_frame [enit] = sprite_17_a;
@@ -549,7 +549,7 @@ void enems_move (void) {
 									#ifdef MODE_128K
 										en_an_state [enit] = GENERAL_DYING;
 										en_an_count [enit] = 12;
-										wyz_play_sound (SFX_KILL_ENEMY_SHOOT);
+										PLAY_SOUND (SFX_KILL_ENEMY_SHOOT);
 									#else															
 										beep_fx (5);
 										en_an_next_frame [enit] = sprite_18_a;
@@ -563,7 +563,7 @@ void enems_move (void) {
 								}
 
 								#ifdef MODE_128K
-									wyz_play_sound (SFX_HIT_ENEMY);
+									PLAY_SOUND (SFX_HIT_ENEMY);
 								#else
 									beep_fx (1);
 								#endif