📁 File

A File represents an entry to a system file.

Client & Server🧑‍💻API Source

---

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.

Allowed Extensions

Only the following file extensions are allowed to be accessed (read & write):

.txt .dat .json .toml .xml .csv .log .png .jpg .jpeg .webp .webm .mp3 .wav .ogg .mp4

note

If you think that a file extension should be added to the allowed list, please report it in the Feedback Hub.

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 read-only access): ../my-package/Client/MyFile.json.

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

🛠 Constructors

Default Constructor

No description provided

local my_file = File(file_path, truncate?)

Parameters

Type	Name	Default	Description
string	file_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
boolean	truncate	false	Whether or not to clear the file upon opening it

🗿 Static Functions

	Returns	Name	Description
	boolean	CreateDirectory	Creates a Directory (for every folder passed)
	boolean	Exists	Verifies if a entry exists in the file system
	table of string	GetDirectories	Gets a list of all directories given a path
	table of string	GetFiles	Gets a list of all files in a directory
	string	GetFullPath	Gets the full path given a relative path based on the current side (client or server)
	boolean	IsDirectory	Checks if a path is a directory
	boolean	IsRegularFile	Checks if a path is a file
	integer	Remove	Deletes a folder or file
	integer	Time	Returns when a file was last modified in Unix time

---

Slow

CreateDirectory

Creates a Directory (for every folder passed)

local ret = File.CreateDirectory(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to folder

Returns

Type	Description
boolean	if succeeded

---

Moderate

Exists

Verifies if a entry exists in the file system

local ret = File.Exists(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to file or folder

Returns

Type	Description
boolean	if exists

---

Slow

GetDirectories

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

local ret = File.GetDirectories(path_filter?, max_depth?)

Parameters

Type	Parameter	Default	Description
string	path_filter?		Path filter
integer	max_depth?	-1	The maximum depth to go further in the folders while searching. Pass -1 for maximum depth

Returns

Type	Description
table of string	List of directories

---

Slow

GetFiles

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

local ret = File.GetFiles(path_filter?, extension_filter?, max_depth?)

Parameters

Type	Parameter	Default	Description
string or table	path_filter?		Path filter
string	extension_filter?		E.g.: .lua
integer	max_depth?	-1	The maximum depth to go further in the folders while searching. Pass -1 for maximum depth

Returns

Type	Description
table of string	List of files

---

Moderate

GetFullPath

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

local ret = File.GetFullPath(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to file or directory

Returns

Type	Description
string	the full path parsed

---

Moderate

IsDirectory

Checks if a path is a directory

local ret = File.IsDirectory(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to folder

Returns

Type	Description
boolean	if is a directory

---

Moderate

IsRegularFile

Checks if a path is a file

local ret = File.IsRegularFile(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to file

Returns

Type	Description
boolean	if is a regular file

---

Slow

Remove

Deletes a folder or file

local ret = File.Remove(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to file or folder

Returns

Type	Description
integer	amount of files deleted

---

Slow

Time

Returns when a file was last modified in Unix time

local ret = File.Time(path)

Parameters

Type	Parameter	Default	Description
string	path	Required parameter	Path to file

Returns

Type	Description
integer	the last update time in unix time

🦠 Functions

	Returns	Name	Description
		Close	Closes the file and destroys the entity
		Flush	Flushes content to the file
	boolean	HasFailed	Checks if the last operation has Failed
	boolean	IsBad	Checks if the file status is Bad
	boolean	IsEOF	Checks if the file status is End of File
	boolean	IsGood	Checks if the file status is Good
	string	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
		ReadAsync	Reads characters from the File asynchronously.
	table	ReadJSON	Reads the whole file as a JSON and returns it.
		ReadJSONAsync	Reads the whole file as a JSON and returns it asynchronously.
	string	ReadLine	Reads and returns the next file line
		Seek	Sets the file pointer to a specific position
	integer	Size	Returns the size of the file
		Skip	Skips n (amount) positions from the current file pointer position
	integer	Tell	Returns the current file pointer position
		Write	Writes the Data at the current position of the file

---

Blocking

Close

Closes the file and destroys the entity

my_file:Close()

---

Blocking

Flush

Flushes content to the file

my_file:Flush()

---

Optimal

HasFailed

Checks if the last operation has Failed

local ret = my_file:HasFailed()

Returns

Type	Description
boolean	if last operation failed

---

Optimal

IsBad

Checks if the file status is Bad

local ret = my_file:IsBad()

Returns

Type	Description
boolean	if status is Bad

---

Optimal

IsEOF

Checks if the file status is End of File

local ret = my_file:IsEOF()

Returns

Type	Description
boolean	if is EOF

---

Optimal

IsGood

Checks if the file status is Good

local ret = my_file:IsGood()

Returns

Type	Description
boolean	if status is Good

---

Blocking

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

local ret = my_file:Read(length?)

Parameters

Type	Parameter	Default	Description
integer	length?	0	Length to be read from file, leave it empty (or 0) to read the whole file

Returns

Type	Description
string	file data

---

Optimal

ReadAsync

Reads characters from the File asynchronously.

my_file:ReadAsync(length?, callback)

Parameters

Type	Parameter	Default	Description
integer	length?	0	Length to be read from file, pass 0 to read the whole file
function	callback	Required parameter	Callback with this format

---

Blocking

ReadJSON

Reads the whole file as a JSON and returns it.

local ret = my_file:ReadJSON()

Returns

Type	Description
table	parsed table

---

Optimal

ReadJSONAsync

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

my_file:ReadJSONAsync(callback)

Parameters

Type	Parameter	Default	Description
function	callback	Required parameter	Callback with the file read with this format

---

Blocking

ReadLine

Reads and returns the next file line

local ret = my_file:ReadLine()

Returns

Type	Description
string	file line data

---

Moderate

Seek

Sets the file pointer to a specific position

my_file:Seek(position)

Parameters

Type	Parameter	Default	Description
integer	position	Required parameter	Position to offset the file pointer

---

Optimal

Size

Returns the size of the file

local ret = my_file:Size()

Returns

Type	Description
integer	file size

---

Optimal

Skip

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

my_file:Skip(amount)

Parameters

Type	Parameter	Default	Description
integer	amount	Required parameter	Amount to offset the file pointer

---

Optimal

Tell

Returns the current file pointer position

local ret = my_file:Tell()

Returns

Type	Description
integer	current file pointer position

---

Slow

Write

Writes the Data at the current position of the file

my_file:Write(data)

Parameters

Type	Parameter	Default	Description
string	data	Required parameter	Data to write to the file

🚀 Events

This class doesn't have own events.