Esta documentación debería acompañar al programa txtPAWS. txtPAWS es un complemento para Paguaglús. Si bien no es necesario utilizarlo para programar en Paguaglús, (ya que éste admite formato SCE PAWS), es mucho más cómodo puesto que automatiza las tareas enormemente.

Se trata de poder utilizar nombres de objetos, localidades y mensajes para referirse a esos objetos en lugar de por sus números de definición en SCE PAWS. También permite dividir un fichero SCE PAWS en trozos, haciendo más manejable el código.

Para saber más acerca de los términos aquí empleados, y sobre qué es una aventura conversacional, consúltese la web del
CAAD

El formato de entrada es SCE PAWS modificado (fichero *.sce), un fichero *.txp

La salida comprende:

1. un fichero .sce con comentarios según las sustituciones. Cada sustitución e inclusión de fichero que se realiza supone incluir un comentario en el punto del programa en el que se produjo. Así:

   ##include objetos.txp
EXAMI ANCHOA PRESENT &&anchoa
MESSAGE &&anchoa_desc
DONE

   Pasa a ser:
   ;##include objetos.txp
...
(contenido de objetos.txp)
...
EXAMI ANCHOA PRESENT 5 ; sustituido &&anchoa por 5
MESSAGE 32 ; sustituido &&anchoa_desc por 32
DONE

2. un fichero .log. Este fichero es sólo informativo. En caso de producirse un error, contiene la información de ese error. Contiene mucha otra información incluso en caso de una compilación correcta.

El fichero .sce generado no es exactamente igual al original, se recomienda guardar siempre el fichero .txp, pues requeriría bastante esfuerzo (aunque sería posible) reconstruirlo.

• PawseZ:
  http://www.geocities.com/TimesSquare/Fortress/9939/index.html
• Paguaglús:
  http://pagina.de/yokiyoki
• PAWS y SCE PAWS:
  http://www.yeandle.plus.com/advent/

El formato de SCE, pawcomp y pawint son copyright de Graham Yeandle.

Un fichero SCE generado con txtPAWS o directamente escrito sin utilizar txtPAWS sirve de entrada para al menos tres compiladores importantes:

1. Paguaglús. Genera directamente código .ulx, es decir, código para la máquina Glulx. (Esta opción es muy recomendable). Es el compilador para el cuál txtPAWS ha sido realizado.
2. El compilador pawseZ de Zak, que genera código inform a partir de un archivo .sce. Esta opción podría ser recomendable, ya que inform puede generar tanto ficheros .z5 (máquina Z) como .ulx (máquina Glulx). Sin embargo, el proyecto pawseZ, pese a ser funcional, es un proyecto sin soporte actualmente.
3. El de Graham Yeandle para MS-DOS, pawcomp. Genera un fichero .pdb que se puede ejecutar con pawint (esta opción no es muy recomendable). pawcomp y pawint están limitados a aventuras de 32k, sin gráficos ni sonidos.

Ejemplo

El tutorial del ticket de PAWS se acompaña como ejemplo, con el nombre mt.txp. Varios otros proyectos están a tu disposición en la carpeta /paguagls/prys.

Instrucciones
Incluir otros ficheros

EL nombre de fichero no puede incluir espacios.
Para hacer esto, debe incluirse la línea:

##include

Por ejemplo:

##include sysmsg.txp

Incluyendo toda la información necesaria, incluso el path si no está en el mismo directorio.
Esto permite factorizar el típico SCE dividido en secciones en varios ficheros más manejables.
También, dependiendo de la habilidad del programador, se podrían definir "librerías", aunque hay que tener presente que las limitaciones de PAWS siguen siendo las mismas, ##include simplemente incluye un fichero de texto en la línea en la que se encuentra.

Definición de identificadores

Al comienzo del programa, antes de cualquier otra sección se puede hacer cualquier definición, objeto, localidad o mensaje y NO se comprueba su validez. Son total responsabilidad del programador. Esta sección se denomina DEF.

La sintaxis es:

##define [obj|flg|loc|msg|snd|msc|pic|grf] identificador numero

• obj = objeto
  Se define en la sección de objetos. Permite referirse a un objeto (un número de 0 a 255) mediante un identificador.

  
/OBJ
/0 1 1 _ _ candelabro _
##define obj candelabro 0

  Más tarde, puede reemplazarse con:

  
ENCIENDE CANDELABRO PRESENT &&candelabro
MESSAGE &&candelabro_encendido_desc
DONE

• flg = bandera
  Se define en la sección de procesos (es el único tipo que se permite definir en la sección de procesos). Permite referirse a un bandera (un número de 0 a 255) mediante un identificador.

  
/PRO 0
##define flg puerta_abierta_sw 80

  Más tarde, puede reemplazarse con:

  
ABRE PUERTA AT &&biblio
PRESENT &&llave
EQ &&puerta_abierta_sw 1
MESSAGE &&puerta_abierta_desc
DONE

• loc = localidad
  Se define en la sección de localidades. Permite referirse a un localidad (un número de 0 a 255) mediante un identificador.

  
/LOC
/1
##define loc biblio 1
La biblioteca de esta gran casa.

  Más tarde, puede reemplazarse con:

  
ABRE PUERTA AT &&biblio
PRESENT &&llave
EQ &&puerta_abierta_sw 1
MESSAGE &&puerta_abierta_desc
DONE

• msg = mensaje
  Se define en la sección de mensajes. Permite referirse a un mensaje (un número de 0 a 2^31) mediante un identificador.

  
/MSG
/1
##define msg puerta_abierta_desc 1
Has abierto la puerta

  Más tarde, puede reemplazarse con:

  
ABRE PUERTA AT &&biblio
PRESENT &&llave
EQ &&puerta_abierta_sw 1
MESSAGE &&puerta_abierta_desc
DONE

• snd = sonido (se reproduce mediante el condacto BEEP)
  Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad).
  La zona DEF es la zona situada entre el comienzo del fichero y la línea /CTL. Es decir, el comienzo del fichero. Permite referirse a un sonido (un número de 0 a 2^31) mediante un identificador.

  
##define snd puerta_abriendose.mod 0
/CTL

  Más tarde, puede reemplazarse con:

  
ABRE PUERTA AT &&biblio
PRESENT &&llave
EQ &&puerta_abierta_sw 1
MESSAGE &&puerta_abierta_desc
BEEP &&puerta_abriendose.mod 0
DONE

• msc = música ambiental (se reproduce automáticamente al entrar en la localidad)
  Se define en la sección de localidades. Permite referirse a un fichero de música asociado a una localidad (un número de 0 a 255) mediante un identificador.

  
/LOC
/1
##define loc biblio 1
##define msc biblio.aif 1
La biblioteca de esta gran casa.

  La música será reproducida al entrar en la habitación "biblio". Nótese que el identificador debe coincidir con el nombre del fichero.

• pic = gráfico (se pinta automáticamente al entrar en la localidad) Se define en la sección de localidades. Permite referirse a un gráfico para una localidad (un número de 0 a 255) mediante un identificador.

  
/LOC
/1
##define loc biblio 1
##define msc biblio.aif 1
##define pic biblio.jpg 1
La biblioteca de esta gran casa.

  El gráfico será pintado al entrar en la habitación "biblio". Nótese que el identificador debe coincidir con el nombre del fichero.

• grf = gráfico (no está relacionado con ninguna localidad)
  Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad).
  La zona DEF es la zona situada entre el comienzo del fichero y la línea /CTL. Es decir, el comienzo del fichero. Permite referirse a un gráfico (un número de 0 a 2^31) mediante un identificador.

  
##define grf puerta_abierta.jpg 1
/CTL

  Más tarde, puede reemplazarse con:

  
ABRE PUERTA AT &&biblio
PRESENT &&llave
EQ &&puerta_abierta_sw 1
MESSAGE &&puerta_abierta_desc
PICTURE &&puerta_abierta.jpg
BEEP &&puerta_abriendose_snd 0
ANYKEY
DESC
DONE

  Nota: el código 0 se refiere siempre al gráfico que se pinta cuando el jugador está a oscuras (de existir).

Por ejemplo:

##define loc loc_inicial 0

En las secciones de objetos, localidades, procesos y mensajes, se pueden definir identificadores: Se aconseja dejar líneas de separación con ';' (el comentario). Por ejemplo:

/LTX
/1
...
/21
esta localidad es una cueva fría
##define loc cueva_fria 21
;


Se comprueba que es un id de localidad ('loc') definida dentro de la localidad, y que el número se corresponde con la localidad actual, para evitar errores.
Véase el fuente del ticket para más ejemplos.

Definición de reemplazos

Se utiliza la siguiente sintaxis:

&&(identificador)

Para reemplazar:
CARRIED 7; llevas la linterna
por:
CARRIED &&linterna ; llevas la linterna
... suponiendo que se haya ##definido el objeto 7 como linterna.

Es IMPORTANTE que haya un espacio delimitando el final del identificador, antes del ';', es decir, del comentario, si éste existe.

Nota

Los símbolos '#' y '&' no pueden ser utilizados duplicados si no se trata de una definición o de un reemplazo. Sobre todo, no se deben utilizar en los textos de los mensajes y localidades. Por ejemplo, si apareciera:

/12
Whisky J&&B

El programa trataría de encontrar un identificador B para sustituirlo, provocando un error de ejecución.

Sí es factible:

/12
Whisky J&B

Errores, sugerencias, comentarios

Ante cualquier error, consultar la línea en el fichero .txp, .txi, .txp.log y txi.log. El programa genera dos ficheros, el .txi donde están todos los ficheros txp ya incluidos, y el sce, cuando ya se han hecho todas las sustituciones. Además, genera otros logs, que describen todos los procesos que realiza.

Si el error sigue sin explicación, consultar el SCE y el log del TXI: ahí se han anotado todas las sustituciones e inclusiones realizadas.

Bugs y dudas

Para cualquier duda o bug encontrado:
Baltasar, el arquero.