Libraries

Uma biblioteca é um script ACS independente que define scripts, funções e constantes comuns, que podem ser usados por outros scripts ACS. Ela é diferente das diretivas padrão #include do ACS porque o arquivo incluído **não é compilado dentro** do binário final resultante.

Usar bibliotecas pode ajudar a economizar espaço nos seus scripts (útil se você usa um editor de scripts com limite de tamanho, como o WadAuthor), além de reduzir duplicação de código e erros de copy-paste. Quaisquer mudanças nas bibliotecas serão refletidas automaticamente em todos os scripts que as utilizam.

O uso mais comum de bibliotecas é em projetos grandes, onde múltiplos mapas compartilham ACS, e também em mods auxiliares de gameplay que incluem seu próprio ACS via LOADACS.

Criando bibliotecas

Um script ACS normal é marcado como biblioteca usando a diretiva #library, que deve ser a primeira instrução no arquivo:

#library "LIBNAME"
#include "zcommon.acs"

O nome passado para a diretiva #library especifica o nome da biblioteca, limitado pelas regras padrão de nomes de lumps em WAD. Depois de compilado, o lump binário deve ser colocado no namespace de bibliotecas ACS com o mesmo nome usado na diretiva #library. Editores modernos de recursos, como o SLADE 3, conseguem automatizar esse processo.

Nota: ao usar LOADACS, scripts ENTER e OPEN dentro da sua biblioteca serão executados em **todo** mapa (seguindo as regras de cada tipo de script).

Importando bibliotecas

Scripts podem importar bibliotecas usando a diretiva #import:

#import "libname.acs"

O caminho passado em #import especifica o fonte não compilado da biblioteca (e não o binário compilado). O caminho pode ser absoluto ou relativo (por exemplo, "/doom/levels/mymaps/foomap/lumps/lib/foolib.acs"). Os seguintes elementos são importados da biblioteca:

Scripts, tanto nomeados quanto numerados (em caso de conflito número/nome, o que for carregado por último é usado (Verification needed))
Funções
Constantes declaradas com a diretiva #libdefine

Nota: quando o ACC varre bibliotecas importadas, todas as diretivas #include dentro da biblioteca são ignoradas e esses arquivos não são varridos.

Exemplo

Abaixo há um exemplo curto e (espero) simples: uma biblioteca de objetivos de fase. Eu comentei mais do que normalmente comentaria, e isso assume que você já tem conhecimento básico de ACS (como loops, if, HudMessage, #define, funções, arrays e variáveis). Se você não tiver, não fique tentando “quebrar a cabeça” com isso (e, se você não conhece essas coisas, provavelmente ainda não deveria estar usando bibliotecas).

//foolib.acs, o arquivo texto do script (biblioteca)
#library "foolib"
#include "zcommon.acs"

#define MAX_OBJECTIVES 4 // número máximo de objetivos por mapa

// este array guarda os objetivos; ele é alterado cada vez que você entra em um novo mapa
world str 0:objectives[];

// esta função é chamada pelo script 999 (veja abaixo)
function void printobjs(void)
{
    HudMessage(s:"Objectives\n\n"; 
        Predefinição:Const | Predefinição:Const, 0, Predefinição:Const, 0.0, 0.0, 5.0 );
    
    // imprime cada objetivo
    for(int x = 0; x < MAX_OBJECTIVES; x++)
    {
        HudMessage(s:objectives[x]; 
            Predefinição:Const | Predefinição:Const, 0, Predefinição:Const, 0.0, (x * 0.1) + 0.1, 5.0);
    }
}

// Este script roda toda vez que você entra em um novo mapa, mostrando os
// objetivos de missão daquele mapa. Se você quiser que o jogador consiga
// ver os objetivos depois que eles sumirem, você precisa configurar um alias
// para “puke 999” em um lump KEYCONF.
script 999 ENTER
{
    printobjs();
    delay(35 * 5); // atraso de cinco segundos
    // note que delays não podem ser colocados em funções, por isso aparece aqui
}

// este é um lump SCRIPTS para o map01
#import "foolib.acs"
#include "zcommon.acs"

script 100 OPEN
{
    objectives[0] = "Find the shotgun";
    objectives[1] = "Get the blue key";
    objectives[2] = "Destroy the computer";
    objectives[3] = "Escape from the complex";
}

// Depois você coloca aqui embaixo os scripts que precisar para o mapa.
// Se quiser, ao completar um objetivo você pode alterar a cor do objetivo
// completado, para o jogador saber que concluiu. Por exemplo: o HudMessage
// imprime tudo em branco; então o script abaixo roda quando você completa
// o primeiro objetivo (objectives[0]).

script 1 (void)
{
    objectives[0] = "\cFFind the shotgun";
    // o \cF no começo da string muda a cor para amarelo (ou dourado)
}

// este é um lump SCRIPTS para o map02
#import "foolib.acs"
#include "zcommon.acs"

script 100 OPEN
{
    objectives[0] = "Kill some imps";
    objectives[1] = "Eat a cheeseburger";
    objectives[2] = "Find a BFG";
    objectives[3] = "";
    // se você não quer que um objetivo apareça, deixe como string vazia
}

Note que este exemplo armazena cada objetivo nos scripts do mapa; você poderia armazenar na biblioteca, mas aí precisaria que os scripts de saída do mapa anotassem para qual mapa você está indo (não é difícil) e então selecionassem o array apropriado na biblioteca ao imprimir os objetivos.