FileAPI

This API is only available on the host.

For more information, see Pings.

FileAPI allows your avatar to access files in isolated folder.

FileAPI is available as global file variable.

Security

FileAPI is fully isolated in your data folder. It is located in your Figura folder, so, default path for it would be figura/data. FileAPI can't access any files or directories out of this folder, even when using symbolic links. Attempt to access file or directory outside data folder will result in error. Every used path in methods is relative to data folder.

Methods

Method	Brief Description
allowed	Checks if FileAPI usage is allowed
isPathAllowed	Checks if a path is allowed for usage
exists	Checks if a path exists
delete	Deletes a file or directory, returning whether it was successful
isDirectory	Checks if a path is a directory
mkdir	Creates a directory
mkdirs	Creates a directory and all parent directories
list	Lists files and directories contained under a path
isFile	Checks if a path is a file
openReadStream	Opens an input stream for a file
openWriteStream	Opens an output stream for a file
readString	Reads a file and returns its contents as a string
writeString	Writes a file's contents as a string

Security checks

Security related methods of FileAPI.

allowed

---

Checks if FileAPI usage is allowed for this avatar.

Overloads:

Arguments	Return Type
allowed()	boolean

-- Prints false on non-host avatar.
print(file:allowed())

isPathAllowed

---

Checks if path is allowed for usage.

Overloads:

Arguments	Return Type
isPathAllowed(path string)	boolean

-- Relative paths are always relative to data folder.
print(file:isPathAllowed("foo")) -- true
-- Relative paths that are pointing outside of data folder are not allowed.
print(file:isPathAllowed("../foo")) -- false
-- Absolute paths pointing to figura data folder are also allowed.
print(file:isPathAllowed("C:/path/to/figura/data/foo")) -- true
-- Absolute paths outside of data folder are not allowed.
print(file:isPathAllowed("C:/foo")) -- false

Common

Methods related both to files and directories.

exists

---

Checks if specified path exists.

Overloads:

Arguments	Return Type
exists(path string)	boolean

print(file:exists("foo.bar")) -- true

delete

---

Deletes file or directory by specified path. Returns true if successful.

Overloads:

Arguments	Return Type
delete(path string)	boolean

-- Directory fooBar is empty
print(file:delete("fooBar")) -- true
-- Directory barFoo has files inside
print(file:delete("barFoo")) -- false
-- foo.bar is not open by any program
print(file:delete("foo.bar")) -- true
-- bar.foo doesn't exist
print(file:delete("bar.foo")) -- false

Directories

Directory related methods of FileAPI.

isDirectory

---

Checks if specified path is directory.

Overloads:

Arguments	Return Type
isDirectory(path string)	boolean

print(file:isDirectory("fooBar")) -- true

mkdir

---

Creates directory by specified path. Returns true if successful.

Overloads:

Arguments	Return Type
mkdir(path string)	boolean

print(file:exists("foo")) -- false
print(file:mkdir("foo")) -- true
print(file:exists("foo")) -- true

@see exists

mkdirs

---

Creates directory by specified path, and all parent directories if they doesn't exist. Returns true if successful.

Overloads:

Arguments	Return Type
mkdir(path string)	boolean

print(file:exists("foo/bar")) -- false
print(file:mkdir("foo/bar")) -- false
print(file:mkdirs("foo/bar")) -- true
print(file:exists("foo/bar")) -- true

@see exists, mkdir

list

---

Lists files and directories by specified path. Returns table with paths, or null if path doesn't exist or not a directory.

Overloads:

Arguments	Return Type
list(path string)	string[] | nil

printTable(file:list("")) --[[{
"foo.bar",
"fooBar",
"barFoo"
}]]

Files

Methods related to files.

isFile

---

Checks if specified path is a file.

Overloads:

Arguments	Return Type
isFile(path string)	boolean

print(file:isFile("foo.bar")) -- true

openReadStream

---

Open input stream for file at specified path. Throws an error if file doesn't exist.

Overloads:

Arguments	Return Type
openReadStream(path string)	InputStream

-- Opens an input stream.
local is = file:openReadStream("foo.bar")

-- Stream must be closed when you finished working with it.
is:close()

@see InputStream:close

openWriteStream

---

Open output stream for file at specified path. Throws an error if unable to create a file.

Overloads:

Arguments	Return Type
openWriteStream(path string)	OutputStream

-- Opens an output stream.
local os = file:openWriteStream("bar.foo")

-- Stream must be closed when you finished working with it.
os:close()

@see OutputStream:close

readString

---

Reads file at specified path and returns it's contents as a string in specified encoding. Default encoding is utf8.

Overloads:

Arguments	Return Type
readString(path string)	string
readString(path string, encoding BufferEncoding)	string

print(file:readString("foo.bar")) -- Hello, world!

writeString

---

Writes string in specified encoding to file by specified path. Default encoding is utf8.

Overloads:

Arguments
writeString(path string, contents string)
writeString(path string, contents string, encoding BufferEncoding)

print(file:writeString("foo.bar", "Hello, world!"))

Navigation

Documentation
Globals	action_wheel animations avatar client config data events figuraMetatables file host json keybinds listFiles matrices models nameplate net parseJson particles pings player print printJson printTable raycast renderer require resources sounds textures toJson type user vanilla_model vec vectors world
APIs (Types)	ActionWheelAPI AnimationAPI AvatarAPI ConfigAPI EntityAPI EventsAPI FileAPI HostAPI MatricesAPI ParticleAPI RendererAPI VectorsAPI ViewerAPI
Visuals (Types)	BlockTask EntityTask ItemTask ModelPart NameplateCustomization NameplateCustomizationGroup EntityNameplateCustomization Particle RenderTask Sound SoundAPI SpriteTask TextTask Texture VanillaPart
Other Types	Action Animation Biome BlockState Buffer Event Future HttpRequestBuilder InputStream ItemStack JsonArray JsonBuilder JsonObject JsonSerializer Keybind Matrix2 Matrix3 Matrix4 OutputStream Page Sound TextureAtlas Vector2 Vector3 Vector4 Vertex
Enums	BlockRaycastTypes Colors EntityPoses FluidRaycastTypes HeightmapTypes ItemDisplayModes Keybinds KeyIDs LoopModes ParentTypes PlayerModelParts PlayStates PostEffects Registries RenderModes RenderTypes StringEncodings TextureTypes UseActions