[Guide] Reading data

[paladin-t]

Most of the structures in Bitty Engine don't offer I/O accessibility directly, it is tied up with Resources, File, etc. instead, and data is transferred through Bytes, Json, string, or table sometimes.

Besides, you may also see Network, fetch(...) for remote I/O, and Path, FileInfo, DirectoryInfo for filesystem traversing.

Note that this page is just a short explanation, read the full manual for details.

Reading assets

Bitty Engine reads assets data via Resources.load(...) for Palette, Texture, Sprite, Map, Sfx, Music. These reading operations are asynchronous, which means it returns a "handle" of that asset and the actual reading happens later. Root of the path parameter starts from project root. Consider calling Resources.unload(...) or Resources.collect() to release unused resources at some point. Note that Texture is different from Image. Bitty Engine infers most of the asset types automatically, except for audio, use hint Sfx or Music to distinguish it explicitly. Resources.load(...) reads from Json, table and other types also, see the full manual for details.

Font is loaded via Font.new(...) synchronously. Same to other resources, root of the path parameter starts from project root.

To read other data, use Project.main:read(...), which returns a Bytes structure synchronously. The cursor of the returned Bytes is at the end, set bytes:poke(1) if any later operation expects it being at the beginning. Again, root of the path parameter starts from project root.

Reading file

Use the following code to open a file for reading:

local file = File.new()
if file:open('somewhere/example.dat', Stream.Read) then
  --[[
    Write your reading code here.
  ]]
  file:close()
end

Then do file:readString(), file:readBytes(), etc. to read its content.

Examples

The following examples shows how to read some data from project assets, use File instead to read from filesystem.

1. Reading Image

local bytes = Project.main:read('somewhere/example.png')
local img = Image.new()
img:fromBytes(bytes)

2. Reading string

local bytes = Project.main:read('somewhere/example.txt')
bytes:poke(1)
local str = bytes:readString()

3. Reading Json data and converting it to Lua table

local bytes = Project.main:read('somewhere/example.json')
bytes:poke(1)
local str = bytes:readString()
local json = Json.new()
json:fromString(str)
local tbl = json:toTable()