Skip to main content
Version: bleeding-edge 🩸

📁 File

A File represents an entry to a system file.

💂Authority
This class can be spawned on both 🟧 Client and 🟦 Server side (if you spawn it on client, it won't be synchronized with other players).
🧑‍💻API Source
This page is auto-generated! The Functions, Properties and Events described here are defined in our GitHub's API Repository! Feel free to commit suggestions and changes to the source .json API files!

info

It is not possible to open files from outside the server folder. All path must be relative to the Server's executable folder. All files are opened as binary file by default.

🎒 Examples

local configuration_file = File("my_awesome_configuration.json")

local configuration_file_json = JSON.parse(configuration_file:Read())

📂 File Access & Sandboxing

Access to files is sandboxed. Only certain directories and files are allowed to be written or read from.

Server Side

On Server side, it's only allowed to access files inside the server folder itself (where server executable is located). Also, accessing the Config.toml is not allowed.

The default directory is where the server executable is located.

Example accessing a file from a Package: Packages/My-Package/Server/MyFile.json.

Client Side

On the client side, we have the concept of the .transient/ folder which is a folder automatically generated inside the client's cached Packages/ folder, where files can be created in a more persistent way.

It's not allowed to access files outside the client's cache folder Packages/, and write access is only permitted inside the .transient/ folder itself.

The default directory is in the client's cached Packages/.transient/ folder.

Example accessing a file from a Package (with ready-only access): ../my-package/Client/MyFile.json.

Example accessing a transient file (with write access): MyFile.json.

🛠 Constructors

Default Constructor

local my_file = File(file_path, truncate?)
TypeNameDefaultDescription
stringfile_path Required parameter If on Server, this is the Path relative to server executable. Otherwise if on Client, this is the Path relative to Client's 'Packages/.transient/' folder
booleantruncatefalseWhether or not to clear the file upon opening it

🗿 Static Functions

ReturnsNameDescription
booleanCreateDirectoryCreates a Directory (for every folder passed)
booleanExistsVerifies if a entry exists in the file system
table of stringGetDirectoriesGets a list of all directories given a path
table of stringGetFilesGets a list of all files in a directory
stringGetFullPathGets the full path given a relative path based on the current side (client or server)
booleanIsDirectoryChecks if a path is a directory
booleanIsRegularFileChecks if a path is a file
integerRemoveDeletes a folder or file
integerTimeReturns when a file was last modified in Unix time

CreateDirectory

Creates a Directory (for every folder passed)

— Returns boolean (if succeeded).

local ret = File.CreateDirectory(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to folder

Exists

Verifies if a entry exists in the file system

— Returns boolean (if exists).

local ret = File.Exists(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to file or folder

GetDirectories

Gets a list of all directories given a path, optionally with filters

— Returns table of string (List of directories).

local ret = File.GetDirectories(path_filter?, max_depth?)
TypeParameterDefaultDescription
stringpath_filter?Path filter
integermax_depth?-1The maximum depth to go further in the folders while searching. Pass -1 for maximum depth

GetFiles

Gets a list of all files in a directory, optionally with filters

— Returns table of string (List of files).

local ret = File.GetFiles(path_filter?, extension_filter?, max_depth?)
TypeParameterDefaultDescription
string or tablepath_filter?Path filter
stringextension_filter?E.g.: .lua
integermax_depth?-1The maximum depth to go further in the folders while searching. Pass -1 for maximum depth

GetFullPath

Gets the full path given a relative path based on the current side (client or server)

— Returns string (the full path parsed).

local ret = File.GetFullPath(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to file or directory

IsDirectory

Checks if a path is a directory

— Returns boolean (if is a directory).

local ret = File.IsDirectory(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to folder

IsRegularFile

Checks if a path is a file

— Returns boolean (if is a regular file).

local ret = File.IsRegularFile(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to file

Remove

Deletes a folder or file

— Returns integer (amount of files deleted).

local ret = File.Remove(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to file or folder

Time

Returns when a file was last modified in Unix time

— Returns integer (the last update time in unix time).

local ret = File.Time(path)
TypeParameterDefaultDescription
stringpath Required parameter Path to file

🦠 Functions

ReturnsNameDescription
CloseCloses the file and destroys the entity
FlushFlushes content to the file
booleanHasFailedChecks if the last operation has Failed
booleanIsBadChecks if the file status is Bad
booleanIsEOFChecks if the file status is End of File
booleanIsGoodChecks if the file status is Good
stringReadReads characters from the File and returns it. Also moves the file pointer to the latest read position. Pass 0 to read the whole file
ReadAsyncReads characters from the File asynchronously.
tableReadJSONReads the whole file as a JSON and returns it.
ReadJSONAsyncReads the whole file as a JSON and returns it asynchronously.
stringReadLineReads and returns the next file line
SeekSets the file pointer to a specific position
integerSizeReturns the size of the file
SkipSkips n (amount) positions from the current file pointer position
integerTellReturns the current file pointer position
WriteWrites the Data at the current position of the file

Close

Closes the file and destroys the entity

my_file:Close()

Flush

Flushes content to the file

my_file:Flush()

HasFailed

Checks if the last operation has Failed

— Returns boolean (if last operation failed).

local ret = my_file:HasFailed()

IsBad

Checks if the file status is Bad

— Returns boolean (if status is Bad).

local ret = my_file:IsBad()

IsEOF

Checks if the file status is End of File

— Returns boolean (if is EOF).

local ret = my_file:IsEOF()

IsGood

Checks if the file status is Good

— Returns boolean (if status is Good).

local ret = my_file:IsGood()

Read

Reads characters from the File and returns it. Also moves the file pointer to the latest read position. Pass 0 to read the whole file

— Returns string (file data).

local ret = my_file:Read(length?)
TypeParameterDefaultDescription
integerlength?0Length to be read from file, leave it empty to read the whole file

ReadAsync

Reads characters from the File asynchronously.

my_file:ReadAsync(length, callback)
TypeParameterDefaultDescription
integerlength Required parameter Length to be read from file, leave it empty to read the whole file
functioncallback Required parameter Callback with this format

ReadJSON

Reads the whole file as a JSON and returns it.

— Returns table (parsed table).

local ret = my_file:ReadJSON()

ReadJSONAsync

Reads the whole file as a JSON and returns it asynchronously.

my_file:ReadJSONAsync(callback)
TypeParameterDefaultDescription
functioncallback Required parameter Callback with the file read with this format

ReadLine

Reads and returns the next file line

— Returns string (file line data).

local ret = my_file:ReadLine()

Seek

Sets the file pointer to a specific position

my_file:Seek(position)
TypeParameterDefaultDescription
integerposition Required parameter Position to offset the file pointer

Size

Returns the size of the file

— Returns integer (file size).

local ret = my_file:Size()

Skip

Skips n (amount) positions from the current file pointer position

my_file:Skip(amount)
TypeParameterDefaultDescription
integeramount Required parameter Amount to offset the file pointer

Tell

Returns the current file pointer position

— Returns integer (current file pointer position).

local ret = my_file:Tell()

Write

Writes the Data at the current position of the file

my_file:Write(data)
TypeParameterDefaultDescription
stringdata Required parameter Data to write to the file

🚀 Events

This class doesn't have own events.