Br:Especificação Hamster Speak

HamsterSpeak é a linguagem usada pelo OHRRPGCE para plotscripting. Este arquivo explica a sintaxe e as palavras reservadas para HamsterSpeak.

Este documento pode parecer soberbo para não programadores, então ao invés disso, você vai querer ler Tutorial Plotscripting, o qual é escrito para iniciantes, e o Dicionário de Comandos PlotScripting.

Sintaxe

HamsterSpeak é um semicompilador que analiza scripts e converte-os em bytecodes (código de máquina) que podem ser fácil e rapidamente analizados por um interpretador como o que será construído no OHRRPGCE.

Funções HamsterSpeak e nomes de variáveis são insensíveis a tamanho e espaços em branco. Os seguintes são todos meios válidos de se escrever o mesmo comando:

 Suspend Player
 suspendplayer
 sUsPeNdPlAyEr
 Susp Endpla Yer

Lembre disto quando estiver nomeando seus scripts e variáveis.

Declarações são separadas por vírgulas e linhas novas. Linhas em branco são ignoradas, e vírgulas duplas são tratadas como vírgulas simples. Você pode usar vírgulas e linhas novas intercaladamente. Por exemplo, os seguintes blocos de código são os mesmos:

 Suspend Player
 Suspend NPCs
 Suspend Obstruction

 Suspend Player, Suspend NPCs, Suspend Obstruction

Muitas das funções HamsterSpeak usam argumentos. Os argumentos para uma função seguem-na em parênteses. Os seguintes são exemplos de funções do HamsterSpeak:

walk hero (me,north,3)
wait for hero (me)
show text box (37)

Além disso, como uma alternativa ao uso de parênteses, você pode usar os comandos begin e end. Isto é útil para tornar funções que usam vários argumentos mais fáceis de olhar.

Os seguintes blocos de código fazem exatamente a mesma coisa

walk hero (me, north, 3)  

walk hero, begin
   me
   north
   3
end  

Você pode usar o símbolo # para colocar comentários em seu script. Qualquer coisa do # para o fim da linha é ignorado.

walk hero, begin
   me      # quem anda? Me!
   north   # esta é a direção que queremos andar
   3       # esta são quantas tiras (espaços) nós queremos andar
end  

Declarações

Existem sete tipos de declarações no HamsterSpeak. script, define script, define function, define constant, define operator, global variable, and variable,

script e definescript

Muito do código no HamsterSpeak é feito em declarações script. Para cada script declarado, deve haver também uma declaração definescript que associa ao script um número ID único, e diz quantos argumentos ele pode aceitar.

Aqui está um script exemplo

Define Script (1,My Script,none)

script, My Script, begin
  # código vem aqui
end

Cada script que você define necessita de um número(1), um nome(My Script), e a contagem de argumentos(none). Scripts que possuem argumentos, necessitam de valores padrão para aqueles argumentos na declaração definescript, e nomes para os argumentos na declaração script.

Aqui está um script exemplo com argumentos

Define Script (2,My Fancy Script,2,0,0)
# este script possui dois argumentos, ambos em zero como padrão

script, My Fancy Script, firstarg, secondarg, begin
  # Este script pode usar os argumentos pelo nome
  # com se eles fossem variáveis locais
end

Ok, agora vamos ver mais detalhadamente a declaração definescript. Todo script que você escreve precisa de um número, um nome, e informação sobre seus argumentos.

include, plotscr.hsd

Define Script (1,My Script,none)
Define Script (2,My Other Script,none)

script, My Script, begin
  # fazer nada
end

script, My Other Script, begin
  # fazer nada
end

O primeiro argumento de definescript é o número id do script. Este é o número pelo qual o OHRRPGCE identifica o script. Dois scripts não podem possuir o mesmo número id

# isto é mau! Ele não vai compilar. MAU! MAU! MAU!
Define Script (1,My Script,none)
Define Script (1,My Other Script,none)

Se você fizer isto, e der o mesmo número para dois scripts, o compilador vai embravecer-se (simplesmente dar erro).

O segundo argumento de definescript é o nome amigável de seu script. Quando o compilador ver My Script no código, ele vai saber que você se refere ao script com ID número 1

Por que scripts precisam de números ID? Porque é como CUSTOM.EXE e GAME.EXE sabem qual script anexar a qual evento, sem ter que lembrar o nome inteiro do script. Mas se você tiver um script que nunca será chamado diretamente por seu jogo, e é apenas chamado por outros scripts, você pode autonumerar o script.

Aqui está um script exemplo que é autonumerado

Define Script (autonumber,My Numberless Script,none)
# este script vai estar escondido no CUSTOM.EXE,
# mas pode ser chamado por outros scripts

script, My Numberless Script, begin
  # blá blá blá
end

Você pode chamar scripts usando seus nomes, da mesma maneira que você chama funções embutidas

definefunction

Para um script fazer uso de qualquer das funções plotscripting, ele precisa de declarações definefunction. Declarações definefunction são como declarações definescript, exceto que elas se referem a funções especiais que são duramente codificadas no interpretador. ( você está ficando sonolento, muito sonolento. Seus olhos estão ficando pesados. Agora você vai dormir. Quando você acordar você vai esquecer qualquer coisa que tenha ouvido sobre "battlescripting". Não há nada semelhante a battlescripting )

Se você tivesse que digitar manualmente suas declarações definefunction, seu código poderia parecer como este, apenas haveriam muiiiiito mais delas:

define function, begin
 0,noop,0
 1,wait,1,1
 2,waitforall,0
 3,waitforhero,1,0
 4,waitfornpc,1,0
 5,suspendnpcs,0
 6,suspendplayer,0
 7,resumenpcs,0
 8,resumeplayer,0
 9,waitforkey,1,99
 10,walkhero,3,0,2,1
 11,showtextbox,1,1
 12,checktag,1,0
 13,settag,2,0,0
 # isto não é tudo! há mais de 120 funções plotscripting!
end

Define Script (1,My Script,none)

script, My Script, begin
  # Eu posso apenas usar funções aqui se elas tiverem sido declaradas
end

Obviamente ninguém quer digitar todo aquele lixo no topo de seu script apenas para fazê-lo rodar, então eu coloquei todas as funções plotscripting em único arquivo chamado plotscr.hsd Tudo que você tem que fazer é adicionar uma declaração include, e todas as funções plotscripting estarão prontas para usar.

include, plotscr.hsd

Define Script (1,My Script,none)

script, My Script, begin
  # Eu posso usar aqui qualquer função que eu quiser,
  # porque todas elas foram declaradas no arquivo incluso.
end

defineconstant

plotscr.hsd também possui algumas constantes para tornar a vida fácil. Graças as constantes, não há necessidade de conhecer quais números o plotscripting usa internamente para representar coisas. As seguintes são algumas das constanters definidas em plotscr.hsd zero, one, two, three, four, five, six, seven, eight, nine, ten, false, true, off, on, north, east, south, west, up, down, left, right, upkey, downkey, leftkey, rightkey, usekey, cancelkey, menukey, anykey, me, none, autonumber...

Outro uso das constantes é a habilidade de referenciar heróis, mapas, músicas, itens, e todo tipo de outras coisas em seu RPG pelo nome ao invés de números. CUSTOM.EXE pode exportar um arquivo incluso (include) de seu Script Management que está cheio de constantes que representam os nomes em seu RPG. Este arquivo vai ter o mesmo nome que seu arquivo RPG, com a extensão HSI (HamsterSpeak Include), e você pode incluí-lo em seu script exatamente da mesma maneira que você inclui o arquivo plotscr.hsd

Você pode adicionar suas próprias constantes para seu script com uma declaração defineconstant

include, plotscr.hsd
include, myrpg.hsi

Define Constant (1000,thousand)
Define Script (1,My Script,none)

script, My Script, begin
  # agora eu posso usar a palavra thousand ao invés de 1000 em meu script
  get money (thousand)
end

defineoperator

O comando defineoperator substitui um operador infixo para uma função ou script que está definido em algum lugar. Hamsterspeak usa isto para suportar operadores matemáticos e lógicos como 1+2. Se você não sabe o que "infixo" significa, ou o que "operadores" são, não se aborreça. Você nunca vai usar defineoperator para nada. Eu apenas mencionei ele aqui por causa da documentação. Se você quiser transformar alguns de seus scripts em operadores, você pode usar PLOTSCR.HSD como um exemplo, ou se corresponder comigo e perguntar.

A parte importante é saber como usar os operadores fixos que já foram definidos para você. O uso mais comum destes operadores é para fazer matemática, e checar igualdades. Para uma lista completa deles, cheque a seção Operator do Dicionário Plotscripting (Plotscripting Dictionary).

Matemáticos: Operadores matemáticos pegam o valor a sua esquerda, e o valor a sua direita, estabelecem matemática entre eles, e retornam o resultado.

include, plotscr.hsd

Define Script (1,Math Sample,none)

script, Math Sample, begin
  variable (n)
  n:=100
  # começamos com 100
  n:=n+5  # agora n é 105
  n:=n*2  # agora n é 210
  n:=n--6 # agora n é 204
  n:=n/4  # agora n é 51
  show value (n)
end

Saiba que o símbolo para subtração é -- Isto é necessário para evitar confusão com nomes de script e constantes que possuem hífens nelas, e números que começam com - para indicar negatividade. Se você quisesse subtrair um número negativo, você deve escrever n -- -6

Comparação e Lógica: Operadores de comparação e lógica pegam o valor a sua esquerda, e o valor a sua direita, compara-os, e retornam verdadeiro ou falso baseado na comparação. Eles são mais usados em declarações if

include, plotscr.hsd

Define Script (1,Comparison Sample,none)

script, Comparison Sample, begin

  if (5==7)
  then,begin
    # cinco nunca é igual a sete, então isto não pode ser verdadeiro
  end

  if (5<<7)
  then,begin
    # cinco é sempre menor que sete, então isto é sempre verdadeiro
  end

  if (5>>7)
  then,begin
    # cinco nunca é maior que sete, então isto não pode ser verdadeiro
  end

  if (5<=random(1,10))
  then,begin
    # Há 50% de chance de que 5 será menor que ou igual ao
    # número aleatório entre 1 e 10, então às vezes isto será
    # verdadeiro e outras vezes será falso
  end

  if (1==1,and,2<>2)
  then,begin
    # um é sempre igual a um, mas dois nunca é diferente de si mesmo
    # então isto nunca pode ser verdadeiro
  end

end

variables

Uma variável é um porta-números nomeado em seu script para o qual você pode dar qualquer valor. Variáveis podem ser globais, o que significa que elas estão disponíveis para qualquer script simples, e são salvas em seu RPG, ou elas podem ser locais, o que significa que elas funcionam apenas no script em que foram criadas, e uma vez que o script termina, elas se vão.

Variáveis globais são definidas com a declaração globalvariable. Como scripts, variáveis globais precisam de números ID únicos.

include, plotscr.hsd

Define Script (1,one script,none)
Define Script (2,another script,none)

Global Variable (1,var)

script, one script, begin
  # Eu posso definir uma variável global em um script...
  var:=100
end

script, one script, begin
  # ...e usá-la em outro
  show value (var)
end

Variáveis locais são declaradas com a declaração variable. Uma variável local sempre inicia como zero quando o script começa. Você pode usar a variável através do script, e quando o script termina, zap! a variável se foi. Se você rodar o script uma segunda vez, ele vai criar tudo de novo. Variáveis locais não precisam de número ID

include, plotscr.hsd

Define Script (1,test script,none)

script, test script, begin
  variable (var)
  # esta variável está disponível apenas para este script
  var:=100
end

Note que globalvariable sempre vai fora de seus scripts. Variable sempre vai dentro de um script. Variáveis locais são criadas logo que o script começa, independente de onde no script você as definiu.

Antigo vs. Novo Estilo de Operadores

Se você escreveu um script HamsterSpeak antes de XX de Dezembro de 1999, você provavelmente usou o estilo antigo de operadores lógicos e matemáticos. Quando você tenta compilar um destes scripts antigos com HSPEAK.EXE versão 1, você pode encontrar erros quando compilar, ou comportamento estranho depois que o script é importado em seu arquivo RPG. Felizmente, aquela falta de compatibilidade com versões anteriores foi corrigida no HSPEAK.EXE versão 2. Você pode usar qual você preferir; as funções no estilo antigo, ou o novo estilo de operadores. Você pode inclusive misturá-los no mesmo script. A exceção notável a isto são os comandos and or e xor. Estes não são compatíveis com versões anteriores. Você precisa usar o estilo operador, não o antigo estilo função.

Estilo Antigo                      Estilo Novo 
add(n,n)                           n+n 
subtract(n,n)                      n--n 
multiply(n,n)                      n*n 
divide(n,n)                        n/n 
modulus(n,n)                       n,mod,n 
exponent(n,n)                      n^n 
equal(n,n)                         n==n 
notequal(n,n)                      n<>n 
lessthan(n,n)                      n<<n 
greaterthan(n,n)                   n>>n 
lessthanorequalto(n,n)             n<=n 
greaterthanorequalto(n,n)          n>=n 
and(n,n)                           n,and,n 
or(n,n)                            n,or,n 
xor(n,n)                           n,xor,n 
set variable(v,n)                  v:=n 
increment(v,n)                     v+=n 
decrement(v,n)                     v-=n 

Para explicações sobre todos os operadores, veja a seção Operadores Matemáticos, de comparação e Lógicos do Dicionário Plotscripting