Files & storage

All paths are relative to the game folder unless they start with / or 0:/. Saving data: use c8b.datastore or c8b.file.writeString — io.open and c8b.file.open are read-only.

Conventions on every page: Availability says whether a symbol exists on the console BIOS, the emulator, or both. c8b and C8B are the same table.

Contents#

• c8b.file
  • c8b.file.exists
  • c8b.file.delete
  • c8b.file.readString
  • c8b.file.writeString
  • c8b.file.isDirectory
  • c8b.file.isdir
  • c8b.file.getSize
  • c8b.file.mkdir
  • c8b.file.rename
  • c8b.file.getFreeSpace
  • c8b.file.getTotalSpace
  • c8b.file.list
  • c8b.file.listDirs
  • c8b.file.listDir
  • c8b.file.listFiles
  • c8b.file.chdir
  • c8b.file.getcwd
  • c8b.file.open
• Constants
  • c8b.file.kFileRead
  • c8b.file.kFileReadData
  • c8b.file.kFileWrite
  • c8b.file.kFileAppend
  • c8b.file.kSeekSet
  • c8b.file.kSeekFromCurrent
  • c8b.file.kSeekFromEnd
• File objects (returned by c8b.file.open)
  • c8b.file.file:read
  • c8b.file.file:readline
  • c8b.file.file:write
  • c8b.file.file:flush
  • c8b.file.file:seek
  • c8b.file.file:tell
  • c8b.file.file:close
• Standard io (replaced by the SDK)
  • io.open
  • iofile:read
  • iofile:lines
  • iofile:close
  • iofile:seek
• Datastore (JSON save files in data/)
  • c8b.datastore.write
  • c8b.datastore.read
  • c8b.datastore.delete
• Low-level bindings (C8B.*)
  • C8B.File_delete
  • C8B.File_exists
  • C8B.File_listDir
  • C8B.File_readString
  • C8B.File_writeString

c8b.file#

c8b.file.exists#

c8b.file.exists(path)

Whether a file or directory exists. Relative paths resolve against the game folder (the working directory).

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.delete#

c8b.file.delete(path)

Deletes a file.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.readString#

c8b.file.readString(path)

Reads a whole file into a string.

• Returns: string or nil
• Availability: Console (BIOS) and emulator

c8b.file.writeString#

c8b.file.writeString(path, data)

Writes (replaces) a file with a string. Working way to write files; see the note on c8b.file.open.

• Returns: boolean
• Availability: Console (BIOS) and emulator

local ok = c8b.file.writeString("data/save.txt", "level=3")

c8b.file.isDirectory#

c8b.file.isDirectory(path)

Whether path is a directory (native).

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.isdir#

c8b.file.isdir(path)

Implemented by listing the parent directory.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.getSize#

c8b.file.getSize(path)

File size in bytes.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.file.mkdir#

c8b.file.mkdir(path)

Creates a directory.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.rename#

c8b.file.rename(oldPath, newPath)

Renames or moves a file.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.getFreeSpace#

c8b.file.getFreeSpace()

Free storage bytes.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.file.getTotalSpace#

c8b.file.getTotalSpace()

Total storage bytes.

• Returns: number
• Availability: Console (BIOS) and emulator

c8b.file.list#

c8b.file.list(dir)

File names in a directory (max 256, no directories).

• Returns: table of strings
• Availability: Console (BIOS) and emulator

c8b.file.listDirs#

c8b.file.listDirs(dir)

Directory names (max 256).

• Returns: table of strings
• Availability: Console (BIOS) and emulator

c8b.file.listDir#

c8b.file.listDir(dir)

Directories first, then files, as {name=..., isDir=...} records.

• Returns: table
• Availability: Console (BIOS) and emulator

c8b.file.listFiles#

c8b.file.listFiles(path, [showHidden])

Listing: names, directories suffixed with "/", dot-files hidden unless showHidden.

• Returns: table of strings
• Availability: Console (BIOS) and emulator

c8b.file.chdir#

c8b.file.chdir(path)

Changes the working directory.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.file.getcwd#

c8b.file.getcwd()

Working directory.

• Returns: string or nil
• Availability: Console (BIOS) and emulator

c8b.file.open#

c8b.file.open(path, [mode=kFileRead])

Opens a file and returns a file object (built on io.open).

• Returns: file or nil, error
• Availability: Console (BIOS) and emulator
• Note: Files can only be opened for reading: kFileWrite and kFileAppend return nil, "write mode not supported". Use c8b.file.writeString to write files.

Constants#

c8b.file.kFileRead#

c8b.file.kFileRead = 3

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kFileReadData#

c8b.file.kFileReadData = 1

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kFileWrite#

c8b.file.kFileWrite = 4

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kFileAppend#

c8b.file.kFileAppend = 8

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kSeekSet#

c8b.file.kSeekSet = 0

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kSeekFromCurrent#

c8b.file.kSeekFromCurrent = 1

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

c8b.file.kSeekFromEnd#

c8b.file.kSeekFromEnd = 2

Mode / seek constant for c8b.file.open and file:seek.

• Availability: Console (BIOS) and emulator

File objects (returned by c8b.file.open)#

c8b.file.file:read#

file:read([n])

Reads n bytes or the rest of the file.

• Availability: Console (BIOS) and emulator

c8b.file.file:readline#

file:readline()

Reads one line.

• Availability: Console (BIOS) and emulator

c8b.file.file:write#

file:write(...)

Writes values. Files cannot be opened for writing, so this has no effect.

• Availability: Console (BIOS) and emulator

c8b.file.file:flush#

file:flush()

Flushes if supported.

• Availability: Console (BIOS) and emulator

c8b.file.file:seek#

file:seek(offset, [whence])

Seeks (kSeekSet/FromCurrent/FromEnd).

• Availability: Console (BIOS) and emulator

c8b.file.file:tell#

file:tell()

Current position.

• Availability: Console (BIOS) and emulator

c8b.file.file:close#

file:close()

Closes.

• Availability: Console (BIOS) and emulator

Standard io (replaced by the SDK)#

io.open#

io.open(path, [mode="r"])

Reads the whole file into memory and returns a handle. Relative paths resolve against the game folder. Any mode other than "r"/"rb" returns nil, "write mode not supported".

• Returns: handle or nil, error
• Availability: Console (BIOS) and emulator

iofile:read#

f:read([mode="*l"])

"*a"/"*all", "*l"/"*line" or a byte count.

• Availability: Console (BIOS) and emulator

iofile:lines#

f:lines()

Line iterator.

• Availability: Console (BIOS) and emulator

iofile:close#

f:close()

Releases the buffer.

• Availability: Console (BIOS) and emulator

iofile:seek#

f:seek([whence="cur"], [offset=0])

Moves the read position.

• Availability: Console (BIOS) and emulator

Datastore (JSON save files in data/)#

c8b.datastore.write#

c8b.datastore.write(table, [name="data"], [pretty])

Encodes the table as JSON and writes data/.json.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.datastore.write({ best = 1200 }, "save")
local s = c8b.datastore.read("save")

c8b.datastore.read#

c8b.datastore.read([name="data"])

Reads data/.json; nil if missing or invalid.

• Returns: table or nil
• Availability: Console (BIOS) and emulator

c8b.datastore.delete#

c8b.datastore.delete([name="data"])

Deletes data/.json.

• Returns: boolean
• Availability: Console (BIOS) and emulator

Low-level bindings (C8B.*)#

C8B.File_delete#

C8B.File_delete(path)

Native file binding: delete.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator

C8B.File_exists#

C8B.File_exists(path)

Native file binding: exists.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator

C8B.File_listDir#

C8B.File_listDir(directory)

Directory listing as {name, isDir} records.

• Returns: 1 value(s): boolean, string
• Availability: Console (BIOS) and emulator

C8B.File_readString#

C8B.File_readString(path)

Native file binding: read string.

• Returns: 1 value(s): _file, nil
• Availability: Console (BIOS) and emulator

C8B.File_writeString#

C8B.File_writeString(path, data, dataLen)

Native file binding: write string.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator