Kainure

Framework para o desenvolvimento moderno de SA-MP com JavaScript e TypeScript.

</div>

Idiomas

Deutsch: README
English: README
Español: README
Français: README
Italiano: README
Polski: README
Русский: README
Svenska: README
Türkçe: README

Índice

Kainure

O que é o Kainure?

O Kainure é um framework que serve como uma ponte entre o tradicional San Andreas: Multiplayer (SA-MP) e o desenvolvimento de software moderno. Ele permite que você escreva toda a lógica do seu gamemode utilizando JavaScript ou TypeScript, abrindo um universo de possibilidades com ferramentas, pacotes e práticas de desenvolvimento atuais.

O plugin integra um ambiente Node.js diretamente no seu servidor SA-MP. A versão específica do Node.js utilizada é a v22.21.1, que traz consigo o poder de componentes de alta performance:

Motor V8: O mesmo motor JavaScript de alta performance do Google Chrome, garantindo que seu código seja executado com velocidade e eficiência impressionantes.
libuv: Uma biblioteca de suporte que gerencia o I/O (operações de entrada e saída) de forma assíncrona, permitindo que seu servidor lide com múltiplas operações simultaneamente sem travar, ideal para um ambiente de jogo dinâmico.

Com o Kainure, você pode deixar de lado as limitações do Pawn e abraçar um ecossistema robusto para criar gamemodes mais complexos, organizados e fáceis de manter.

Como Instalar e Usar

1. Download

A versão mais recente do Kainure, incluindo o plugin e todos os arquivos necessários, pode ser encontrada na página de Releases do projeto.

2. Estrutura de Arquivos

Após o download, você precisa organizar os arquivos na raiz do seu servidor SA-MP da seguinte forma:

/ (Raiz do Gamemode)
├── plugins/
│   └── Kainure.dll  (ou Kainure.so no Linux)
├── Kainure/
│   ├── core/
│   ├── types/
│   ├── kainure.js
│   └── config.json (será criado na primeira inicialização se não existir)
└── libnode.dll (ou libnode.so no Linux)

Importante:

O plugin Kainure deve ser adicionado ao seu arquivo server.cfg.
A biblioteca libnode (.dll ou .so) deve estar na raiz do servidor, junto com o executável samp-server (ou samp03svr no Linux).

3. Configuração (config.json)

Dentro da pasta Kainure/, você encontrará o arquivo config.json. Se ele não existir, o plugin o criará automaticamente na primeira vez que for executado. Este arquivo controla o comportamento do framework.

{
    "configs": {
        "main_file": "./main.js",
        "encoding": {
            "enabled": false,
            "target": 65001
        }
    },
    "typescript": {
        "enabled": false,
        "output_dir": "./dist"
    }
}

main_file: Este é o ponto de entrada do seu gamemode. O Kainure começará a executar o código a partir deste arquivo. Por padrão, ele pode ser .js ou .ts (se o TypeScript estiver ativado). O caminho ./ representa a raiz do seu gamemode.
encoding.enabled: Define se o Kainure deve converter as strings entre o formato UTF-8 (padrão do JavaScript) e a codificação do seu servidor. Se definido como false, o framework utilizará o padrão 65001 (UTF-8).
encoding.target: Define a codificação alvo.
- Windows: É obrigatório o uso do número da Codepage (ex: 1252).
- Linux: É obrigatório o uso do nome da Codepage (ex: WINDOWS-1252).
typescript.enabled: Mude para true se você deseja escrever seu código em TypeScript. O Kainure irá transpilar automaticamente os arquivos .ts para .js.
typescript.output_dir: Define o diretório onde os arquivos JavaScript transpilados serão salvos.

API e Funcionalidades

Filosofia: Globais e Sem Complicação

O Kainure foi projetado para ser intuitivo. Você não precisa importar ou require nenhum dos módulos principais (api.js, commands.js, etc.) nos seus arquivos. O framework carrega e injeta automaticamente todas as suas funcionalidades no escopo global (globalThis), tornando-as imediatamente acessíveis em qualquer parte do seu código.

Módulo Principal: `api.js`

Este módulo contém as funções essenciais para interagir com o servidor SA-MP.

`Float`

Garante que um número seja tratado como float, mesmo que ele possa ser interpretado como um inteiro. Isso é crucial para nativas do SA-MP que exigem floats.

Quando usar? Use Float() apenas quando o valor é dinâmico e desconhecido em tempo de compilação (por exemplo, vindo de um comando ou de outra função). Seu uso manual é relevante somente ao passar valores para Native. e Call_Public..

[!IMPORTANT] Se você escrever um valor explícito no código, como 50.0, o pré-processador de código do Kainure automaticamente aplicará o tratamento de Float antes de enviá-lo para o motor V8. Portanto, o uso manual só é necessário em casos específicos.

Command('sethealth', (playerid, params) => {
    const health = { value: 0.1 }; // "0.1" para o JavaScript não otimizar para inteiro.

    if (!Command_Params(params, "f", health))
        return Native.SendClientMessage(playerid, -1, "Uso: /sethealth [vida]");

    // `health.value` é desconhecido, então usamos Float() para garantir a tipagem correta.
    Native.SetPlayerHealth(playerid, Float(health.value));
});

`Ref`

Marca uma variável para receber um valor por referência de uma função nativa.

Como funciona?

Para receber um valor de uma nativa (parâmetros de saída), use a sintaxe .$ ao passar a variável.
Para passar o valor contido na variável para uma nativa, use-a normalmente.
O valor inicial passado para Ref() determina o tipo de dado esperado.

Inicialização:

int: Ref() ou Ref(0)
float: Ref(0.1) (ou qualquer float que não termine em zero absoluto, para evitar otimização para inteiro pelo JavaScript)
string: Ref("")
bool: Ref(true) ou Ref(false)

Command('health', (playerid) => {
    const health = Ref(0.1); // Esperamos receber um float.

    // Usamos health.$ para que a nativa preencha a variável com a vida do jogador.
    Native.GetPlayerHealth(playerid, health.$);

    // Usamos somente `health` para ler o valor. O Ref é convertido automaticamente para seu valor.
    Native.SendClientMessage(playerid, -1, `Sua vida: ${health}`);
});

`Public`

Declara uma callback (public) do SA-MP, permitindo que seu código reaja a eventos do jogo.

Assinaturas de Parâmetros: Para que o Kainure converta os tipos corretamente, é obrigatório fornecer uma assinatura como segundo parâmetro caso a callback possua argumentos.

i: Inteiro
f: Float
s: String
b: Booleano

Validações e Erros: O Kainure impede a execução se:

A função possuir parâmetros, mas nenhuma assinatura for fornecida.
A quantidade de caracteres na assinatura for diferente da quantidade de parâmetros definidos na função.
A assinatura contiver tipos inválidos (diferentes de i, f, s, b).

Valores de Retorno:

return 1; ou return true;: Permite que a callback continue a ser executada em outros scripts (se houver). Este é o comportamento

Kainure

Install / Use

README

Kainure

Idiomas

Índice

O que é o Kainure?

Como Instalar e Usar

1. Download

2. Estrutura de Arquivos

3. Configuração (config.json)

API e Funcionalidades

Filosofia: Globais e Sem Complicação

Módulo Principal: api.js

Float

Ref

Public

Módulo Principal: `api.js`

`Float`

`Ref`

`Public`