Arquivos

Essas funções leem e escrevem arquivos dentro da pasta do resource que está rodando o script. O handle devolvido por fileOpen e fileCreate é um número no servidor e um elemento file no cliente (getElementType devolve "file").

Um arquivo aberto é carregado inteiro para a memória. Tudo que você escreve vai para essa cópia — o disco só é atualizado quando você chama fileFlush, quando fecha o arquivo com fileClose, ou quando o resource para (nesse momento todos os arquivos que ficaram abertos são gravados e fechados automaticamente).

No cliente

O cliente tem regras de arquivo próprias, que diferem das do servidor em vários pontos:

• Um caminho que começa com @ aponta para um dos arquivos privados do resource, guardados separadamente para cada servidor; sem ele o arquivo é público.
• Um arquivo que o manifest não lista é criado na pasta de dados do MTAX do jogador e continua lá na próxima conexão. Alterações em um arquivo baixado (listado no manifest) ficam só na memória, durante a sessão.
• Um caminho é recusado quando está vazio, termina em /, ou contém algo além de caracteres ASCII visíveis, um : fora do :outroResource/ inicial, ou ...
• fileCreate, fileCopy e fileRename recusam nomes de arquivos executáveis (.exe, .dll, .bat, .js, .lnk e semelhantes) com um aviso.
• Destruir o elemento do arquivo fecha o arquivo como fileClose. Um elemento de arquivo que o script deixa de referenciar é fechado pelo coletor de lixo, com um aviso.
• O fileOpen ainda não lê o arquivo: o conteúdo é carregado pela primeira chamada que precisa dele — fileRead, fileWrite, fileGetContents ou fileGetHash —, então abrir um arquivo grande só para chamar fileGetSize não gasta memória. Se essa leitura falhar, a chamada registra unable to load file e devolve false (nil no fileGetHash).

Regras de caminho (servidor)

Todo caminho é resolvido a partir da pasta do resource. A única forma de sair dela é o formato :outroResource/arquivo.txt descrito abaixo, e ele só lê, nunca escreve.

São recusados:

• caminhos absolutos, ou seja, começando com /;
• qualquer caminho que contenha : fora do :outroResource/ inicial, incluindo letras de unidade (C:/dados.txt);
• segmentos . ou .. em qualquer posição (../senhas.txt, dados/../../x);
• barras duplicadas, como dados//lista.txt;
• caminho vazio ou com mais de 1024 caracteres.

Barras invertidas são aceitas e convertidas para /, e um @ no começo do caminho é ignorado. Quando o caminho é recusado a função simplesmente falha — devolve false ou nil — e nenhum arquivo é lido, criado ou apagado.

Nota

O tamanho máximo de um arquivo no servidor é 50 MiB (52.428.800 bytes). Arquivos maiores não abrem, e uma escrita que ultrapassaria esse limite é interrompida.

Ciclo completo — criar, escrever, ler e fechar

local caminho = "logs/entradas.txt"

local arquivo
if fileExists(caminho) then
    arquivo = fileOpen(caminho)      -- abre para leitura e escrita
else
    arquivo = fileCreate(caminho)    -- cria o arquivo (e a pasta logs/ junto)
end

if arquivo then
    fileSetPos(arquivo, fileGetSize(arquivo))   -- posiciona no fim
    fileWrite(arquivo, "jogador entrou\n")

    fileSetPos(arquivo, 0)                      -- volta para o começo
    outputDebugString(fileGetContents(arquivo, false))   -- false: pula a conferência de download do cliente

    fileClose(arquivo)                          -- grava no disco e libera o handle
end

Alcançando outro resource

Um caminho que começa com : aponta para um arquivo dentro de outro resource:

local arquivo = fileOpen(":core/lib/versao.txt")

No servidor, só funciona quando o seu próprio mtaxmanifest.lua declarou aquele caminho como uma entrada emprestada. Declarar é a permissão — o outro resource nunca é consultado:

-- mtaxmanifest.lua do resource que vai ler
files = {
    ":core/lib/versao.txt",
    ":core/data/**/*.json",
}

As regras:

• Só leitura. fileCreate, fileDelete, fileRename e o destino de fileCopy nunca saem da sua própria pasta; um caminho com : ali simplesmente falha.
• Um handle de fileOpen sobre um arquivo emprestado é sempre somente leitura, independente do que você passou em readOnly. fileWrite nele falha e nada é gravado de volta.
• Só o que você declarou fica visível. Um caminho fora dos seus globs declarados falha exatamente como se o arquivo não existisse, e o pathListDir esconde as entradas sobre as quais você não tem direito.
• Um glob declarado no manifest continua valendo como glob aqui: ":core/data/**/*.json" abre qualquer um desses arquivos pelo nome.
• Escrever o nome do seu próprio resource depois do : é permitido e significa o mesmo que o caminho puro.

As funções que aceitam o formato são fileExists, fileOpen, fileCopy (só a origem), loadfile, pathListDir, pathIsFile e pathIsDirectory.

Nota

No cliente nenhuma dessas regras vale. :outroResource/ alcança qualquer resource iniciado na máquina daquele jogador, sem declaração no manifest, e serve tanto para escrever quanto para ler: fileCreate, fileDelete, fileRename e fileCopy também aceitam o formato, e um handle que fileOpen devolve sobre um arquivo de outro resource aceita escrita, a menos que você passe readOnly. Um resource que não está iniciado no cliente não pode ser alcançado.

Estas 21 funções existem no servidor e no cliente. Você pode usá-las em scripts declarados em server_files, client_files ou shared_files.

fileOpen Abre um arquivo existente.

fileCreate Cria um arquivo novo, ou zera um que já exista.

fileClose Grava as alterações pendentes no disco e fecha o arquivo.

fileFlush Grava no disco o que foi escrito até agora, sem fechar o arquivo.

fileRead Lê bytes a partir da posição atual.

fileWrite Escreve uma ou mais strings a partir da posição atual.

fileGetContents Devolve o conteúdo inteiro do arquivo.

fileGetSize Devolve o tamanho do arquivo em bytes.

fileGetPos Devolve a posição atual de leitura e escrita.

fileSetPos Move a posição de leitura e escrita.

fileIsEOF Verifica se a posição chegou ao fim do arquivo.

fileGetPath Devolve o caminho do arquivo aberto.

fileGetHash Calcula o hash do conteúdo do arquivo.

fileExists Verifica se um arquivo existe.

fileCopy Copia um arquivo.

fileRename Renomeia ou move um arquivo.

fileDelete Apaga um arquivo.

loadfile Compila um arquivo Lua do resource e devolve como função, sem executá-lo.

pathListDir Lista os nomes que estão diretamente dentro de uma pasta do resource.

pathIsFile Diz se um caminho é um arquivo.

pathIsDirectory Diz se um caminho é uma pasta.