Trabalhando com arquivos

Há muitas formas diferentes de criar e/ou acessar arquivos. Os caminhos de arquivo e as formas de acessar esses arquivos variam dependendo do tipo de arquivo e de sua localização.

Funções para acesso a arquivos e pastas

O Defold fornece várias funções diferentes para trabalhar com arquivos:

• Você pode usar as funções padrão io.* para ler e escrever arquivos. Essas funções oferecem controle muito detalhado sobre todo o processo de I/O.

-- abre myfile.txt para escrita em modo binário
-- retorna nil mais uma mensagem de erro em caso de falha
local f, err = io.open("path/to/myfile.txt", "wb")
if not f then
	print("Something went wrong while opening the file", err)
	return
end

-- escreve no arquivo, faz flush para o disco e então fecha o arquivo
f:write("Foobar")
f:flush()
f:close()

-- abre myfile.txt para leitura em modo binário
-- retorna nil mais uma mensagem de erro em caso de falha
local f, err = io.open("path/to/myfile.txt", "rb")
if not f then
	print("Something went wrong while opening the file", err)
	return
end

-- lê o arquivo inteiro como uma string
-- retorna nil em caso de falha
local s = f:read("*a")
if not s then
	print("Error while reading file")
	return
end

print(s) -- Foobar

• Você pode usar os.rename() e os.remove() para renomear e remover arquivos.

• Você pode usar sys.save() e sys.load() para ler e escrever tabelas Lua. Funções adicionais sys.* existem para ajudar na resolução de caminhos de arquivo independente de plataforma.

-- obtém um caminho independente de plataforma para o arquivo "highscore" da aplicação "mygame"
local path = sys.get_save_file("mygame", "highscore")

-- salva uma tabela Lua com alguns dados
local ok = sys.save(path, { highscore = 100 })
if not ok then
	print("Failed to save", path)
	return
end

-- carrega os dados
local data = sys.load(path)
print(data.highscore) -- 100

Localizações de arquivos e pastas

Localizações de arquivos e pastas podem ser divididas em três categorias:

• Arquivos específicos da aplicação criados pela sua aplicação
• Arquivos e pastas empacotados com sua aplicação
• Arquivos específicos do sistema acessados pela sua aplicação

Como salvar e carregar arquivos específicos da aplicação

Ao salvar e carregar arquivos específicos da aplicação, como recordes, configurações do usuário e estado do jogo, recomenda-se usar uma localização fornecida pelo sistema operacional e destinada especificamente a essa finalidade. Você pode usar sys.get_save_file() para obter o caminho absoluto específico do sistema operacional para um arquivo. Depois de ter o caminho absoluto, você pode usar as funções sys.*, io.* e os.* (veja acima).

Veja o exemplo que mostra como usar sys.save() e sys.load().

Como acessar arquivos empacotados com a aplicação

Você pode incluir arquivos com sua aplicação usando bundle resources e custom resources.

Custom Resources

Custom resources são incluídos no arquivo principal do jogo usando o campo Custom Resources em game.project.

O campo Custom Resources deve conter uma lista separada por vírgulas de recursos que serão incluídos no arquivo principal do jogo. Se diretórios forem especificados, todos os arquivos e diretórios dentro desse diretório serão incluídos recursivamente. Você pode ler os arquivos usando sys.load_resource().

-- Carrega dados de nível em uma string
local data, error = sys.load_resource("/assets/level_data.json")
-- Decodifica a string json para uma tabela Lua
if data then
  local data_table = json.decode(data)
  pprint(data_table)
else
  print(error)
end

Bundle Resources

Bundle resources são arquivos e pastas adicionais localizados como parte do bundle da sua aplicação usando o campo Bundle Resources em game.project.

O campo Bundle Resources deve conter uma lista separada por vírgulas de diretórios com arquivos e pastas de recursos que devem ser copiados como estão para o pacote resultante ao empacotar. Os diretórios devem ser especificados com um caminho absoluto a partir da raiz do projeto, por exemplo /res. O diretório de recursos deve conter subpastas nomeadas por platform, ou architecture-platform.

As plataformas suportadas são ios, android, osx, win32, linux, web, switch. Uma subpasta chamada common também é permitida, contendo arquivos de recursos comuns a todas as plataformas. Exemplo:

res
├── win32
│   └── mywin32file.txt
├── common
│   └── mycommonfile.txt
└── android
    ├── myandroidfile.txt
    └── res
        └── xml
            └── filepaths.xml

Você pode usar sys.get_application_path() para obter o caminho onde a aplicação está armazenada. Use esse caminho base da aplicação para criar o caminho absoluto final para os arquivos que você precisa acessar. Depois de ter o caminho absoluto desses arquivos, você pode usar as funções io.* e os.* para acessá-los.

local path = sys.get_application_path()
local f = io.open(path .. "/mycommonfile.txt", "rb")
local txt, err = f:read("*a")
if not txt then
	print(err)
	return
end
print(txt)

Recursos Custom e Bundle - comparação

Acesso a arquivos do sistema

O acesso a arquivos do sistema pode ser restrito pelo sistema operacional por motivos de segurança. Você pode usar a extensão nativa extension-directories para obter o caminho absoluto de alguns diretórios comuns do sistema (por exemplo, documents, resource, temp). Depois de ter o caminho absoluto desses arquivos, você pode usar as funções io.* e os.* para acessá-los (veja acima).

Extensões

O Portal de Assets contém vários assets para simplificar o acesso a arquivos e pastas. Alguns exemplos:

• Lua File System (LFS) - Funções para trabalhar com diretórios, permissões de arquivo etc.
• DefSave - Um módulo para ajudar você a salvar/carregar configurações e dados do jogador entre sessões.