File System Overview

The file system is a storage sandbox scoped by host and user, plus a set of management APIs. Call tj.getFileSystemManager() to get the singleton FileSystemManager for all file operations.

var fs = tj.getFileSystemManager()

Files come in two buckets:

• Code package files: files shipped in your project bundle.
• Local files: files created locally via APIs or downloaded and stored on the device.

Local files split into three types:

• Local temp files: created on the fly, can be reclaimed anytime. No size limit.
• Local cached files: produced by caching a local temp file via the host APIs; directory and filename aren’t configurable.
• Local user files: also produced by caching a local temp file, but you can choose the directory and filename.

Code Package Files

Because the bundle has size limits, use code package files for assets needed on first load. For larger or frequently updated content, download to local storage after the game starts.

Accessing Code Package Files

Paths in the bundle start at the project root; relative paths aren’t supported. For example:

• Valid: /a/b/c, a/b/c
• Invalid: .a/b/b, ../a/b/c

Modifying Code Package Files

Bundle files can’t be changed or deleted at runtime. To update them, publish a new version.

Local Files

Once the mini game is installed, it gets an isolated storage area per user. On the same device, users can’t access each other’s files, and different appIds for the same user can’t see one another either. Local file paths follow this format:

{{protocol}}://path-to-file

The protocol is tjfile on iOS/Android/PC hosts.

Local Temp Files

Temp files only come from specific APIs; you can’t write them directly. They’re only valid for the current lifecycle and won’t survive a restart. Don’t stash a temp file path for reuse. If you need it later, convert it via FileSystemManager.saveFile() or FileSystemManager.copyFile() into a cached file or user file.

Example

tj.chooseImage({
  success: function (res) {
    var tempFilePaths = res.tempFilePaths // each item is a local temp file path
  }
})

Local Cached Files

Cached files only come from specific APIs; you can’t write them directly. They survive restarts. Use FileSystemManager.saveFile() to persist a temp file as a cached file.

Example

fs.saveFile({
  tempFilePath: '', // pass a local temp file path
  success(res) {
    console.log(res.savedFilePath) // res.savedFilePath is a local cached file path
  }
})

Local User Files

The host exposes a user file directory with full read/write access. Get its path via tj.env.USER_DATA_PATH.

Example

const fs = tj.getFileSystemManager()
fs.writeFileSync(`${tj.env.USER_DATA_PATH}/hello.txt`,  'hello, world', 'utf8')

Read/Write Permissions

API / Component	Read	Write
Code package	Yes	No
Local temp	Yes	No
Local cached	Yes	No
Local user	Yes	Yes

Cleanup Strategy

• Local temp files only last for the current host lifecycle; once the host closes they may be reclaimed, so they aren’t guaranteed after a cold start.
• Local cached files and local user files are cleaned alongside the code package—they’re removed only when the bundle is cleared.