The File System plugin allows read and write access to files and folders on the local system.
For a demonstration of using file system features, see the Text Editor example.
Browser/platform support
For the File System plugin features to work, the browser must support the full File System Access API. (Note that Origin Private File System or OPFS is not used by the File System plugin.) As of July 2023 this is only supported in Chrome and Edge (and most other Chromium-based browsers) on desktop. Notably this means Firefox, Safari, and mobile devices are not currently supported. However it is also supported in the NW.js exporter and the Windows WebView2 exporter.
Permissions model
Browsers impose security restrictions to ensure that general web browsing is safe. Therefore they start with no access to local files or folders at all. The only way to gain access to local files and folders is to show a picker - a "save file" dialog, an "open file" dialog, or a "pick folder" dialog. (The one exception to this is accessing known folders in Windows WebView2 exports - see below.) Once the user has successfully completed a picker by making a selection and clicking OK, then permission to access the chosen files or folders is granted. This may be different to other tools where direct file system access via file paths is automatically permitted.
In some circumstances browsers will also show a permission prompt to access a file. For example choosing a file with an "open file" picker allows reading the file without any further permission prompt, as the picker grants read access. However if later on an attempt is made to write to the opened file, browsers will normally show a permission prompt to verify that the user is willing to allow their previously chosen file to be modified. This only applies to browsers though - NW.js and WebView2 exports will not show permission prompts (although they must still use pickers first to gain access to files and folders).
To help avoid the need to keep showing pickers, Construct is also able to save the permission to access previously chosen files and folders. The Has picker tag condition will be true if a picker completed in a prior session and the same chosen files or folders can still be accessed. Browsers may also show permission prompts when accessing files or folders from prior sessions.
Picker tags and file tags
Tags are short pieces of text used to identify different uses of the same feature. The File System plugin uses two kinds of tags. Picker tags identify different picker dialogs, such as two different uses of an "open file" dialog. Each successfully completed picker grants access to the chosen files or folders, which are then referred to by the picker tag.
Reading or writing a file then uses a file tag. This identifies the actual file system operation of reading or writing to a chosen file or folder. The file tag is optional as it's only needed if you want to track when file system operations complete or encounter an error - if you don't care about the result, you can leave the file tag empty.
The reason two kinds of tags are used is because one picker may grant access to multiple files or folders. For example one folder picker can grant access to a folder, in to which two files are then written. In this case there is one picker tag identifying the folder the user chose, and then two file tags identifying the separate write operations.
In summary picker tags are required in order to identify the files and folders the user chose, but file tags are optional and are used to identify when reading or writing specific files or folders completes or encounters an error.
Accessing known folders
In Windows WebView2 exports only, the browser permission model can be bypassed to directly access folders such as the user's Documents folder. This is done by using pre-defined folder picker tags like "<documents>". These act like the folder was already picked on startup. You can check if these are available on startup by using the Has picker tag condition. If available then actions like Write text file can write to picker tag "<documents>" folder path "test.txt", in order to write "text.txt" in the user's Documents folder, without showing any picker dialog or permission prompts at all.
The full table of pre-defined picker tags for known folders is listed below. Note not all of these are guaranteed to be available: a system may not have some types of folders, in which case Has picker tag will be false even in Windows WebView2 exports. Also note the example paths are for illustrative purposes only - the specific paths accessed may be different depending on the username, and may be in entirely different locations depending on the application install directory or system configuration.
| Picker tag |
Description |
| <app> |
Folder main application executable belongs to.
Example: C:\Program Files\My app |
| <web-resource> |
The folder that contains web resource files such as index.html, typically in a www subfolder to the app folder.
Example: C:\Program Files\My app\www |
| <current-app-data> |
The local app data folder for this specific application.
Example: C:\Users\username\AppData\Local\myapp |
| <local-app-data> |
The main system local app data folder for the current user.
Example: C:\Users\username\AppData\Local |
| <roaming-app-data> |
The main system roaming app data folder for the current user.
Example: C:\Users\username\AppData\Roaming |
| <desktop> |
User's desktop folder.
Example: C:\Users\username\Desktop |
| <documents> |
User's documents folder.
Example: C:\Users\username\Documents |
| <downloads> |
User's downloads folder.
Example: C:\Users\username\Downloads |
| <pictures> |
User's pictures/photos folder.
Example: C:\Users\username\Pictures |
| <profile> |
Parent folder for all files and folders relating to the current user.
Example: C:\Users\username |
| <saved-games> |
User's folder for games to save their current progress to.
Example: C:\Users\username\Saved Games |
| <screenshots> |
User's folder for games and applications to save screenshots to. Note this may be a subfolder to the pictures folder.
Example: C:\Users\username\Pictures\Screenshots |
| <videos> |
User's folder for games and applications to save recorded videos to.
Example: C:\Users\username\Videos |
File system conditions
- Has picker tag
- True if a given picker tag has been remembered from a previous session. In this case the picker tag can still be referred to for file system operations, such as to read a previously chosen file, without having to show a picker again.
- On picker complete
- On picker error
- Triggered after the Show folder picker, Show open file picker or Show save file picker actions with a matching picker tag, depending on the result of the picker. A picker is completed when the user successfully chooses a file or folder and access is then granted to the selection. Cancelling a picker, or otherwise being unable to show a picker (e.g. due to not being in a user input trigger), will trigger On picker error.
- Is supported
- True if file system features are supported. This depends on support for the File System Access API in the browser. If false then none of the features of the plugin will work.
- On file operation complete
- On file operation error
- Triggered after any file or folder operation such as reading a file or creating a folder, with a matching file tag completes/fails.
- On any file operation complete
- On any file operation error
- Triggered after any file or folder operation such as reading a file or creating a folder completes/fails, regardless of its file tag. The associated file tag can be retrieved with the FileTag expression.
File system actions
- Add accept type
- Add a file type to be shown in the next open file or save file picker. By default the pickers will show all kinds of files; adding an accept type defaults to filtering by those kinds of files, and adding multiple accept types allows the user to switch between different filters. The accept type must specify a MIME type, such as "text/plain" for text files or "image/png" for PNG images. A list of file extensions can also be provided in case they cannot be deduced from the MIME type. These must begin with a dot and multiple file extensions can be specified separated by semicolons, e.g. ".png;.jpg" indicates to allow both .png and .jpg file extensions. A description can also be provided which may be shown in the picker. When the next picker is shown, the list of added accept types is cleared and must be added again for another picker; typically you should use this action immediately prior to showing a picker.
- Show folder picker
- Show a folder picker allowing the user to choose a folder on their local system. The Picker tag identifies the chosen folder if it is completed successfully. The Mode determines what kind of permission prompt the user is shown. The Picker ID is an optional extra identifier for remembering the picker settings, such as the last viewed folder. The Start in setting allows choosing a default system folder to show as the initial selection of the folder picker, but is overridden by any remembered settings from the same Picker ID.
- Show open file picker
- Show an open file picker allowing the user to choose one or multiple files on their local system to open. The Picker tag identifies the chosen file or files if it is completed successfully, and grants read access. (The files can later be written to, but the browser will show another permission prompt.) Show accept all sets whether to show an accept type that shows all kinds of files; if disabled then the Add accept type action must be used beforehand. Multiple can be enabled to allow the user to select multiple files in the open file picker. The Picker ID is an optional extra identifier for remembering the picker settings, such as the last viewed folder. The Start in setting allows choosing a default system folder to show as the initial selection of the folder picker, but is overridden by any remembered settings from the same Picker ID.
- Show save file picker
- Show a save file picker allowing the user to choose a file on their local system to save to. The Picker tag identifies the chosen file if it is completed successfully, and grants write access. Show accept all sets whether to show an accept type that shows all kinds of files; if disabled then the Add accept type action must be used beforehand. The Suggested name is used as the initial filename choice to save to in the picker. The Picker ID is an optional extra identifier for remembering the picker settings, such as the last viewed folder. The Start in setting allows choosing a default system folder to show as the initial selection of the folder picker, but is overridden by any remembered settings from the same Picker ID.
- Read text file
- Read binary file
- Read the contents of a file from a previously completed picker. The file or folder to read from is identified by the Picker tag. The Folder path is optional and is only used for folder pickers or from a open picker with Multiple enabled, and specifies the filename to be read, e.g. "file1.txt" or "subfolder/file2.txt" when using a folder picker. When using a save file picker or an open file picker for a single file, leave the Folder path empty as it is not used, as it will read the single file chosen by the picker. The File tag is optional and allows identifying when the read operation completes or fails with the On file operation complete/error triggers. In the case of reading a text file, the FileText expression is set to the read text content when completed. In the case of reading a binary file, the read file contents will be placed in the chosen Binary Data object when completed.
- Write text file
- Write binary file
- Write text or binary data to a file from a previously completed picker. The file or folder to write to is identified by the Picker tag. The Folder path is optional and is only used for folder pickers or from a open picker with Multiple enabled, and specifies the filename to be written to, e.g. "file1.txt" or "subfolder/file2.txt" when using a folder picker. When using a save file picker or an open file picker for a single file, leave the Folder path empty as it is not used, as it will write to the single file chosen by the picker. The File tag is optional and allows identifying when the write operation completes or fails with the On file operation complete/error triggers. In the case of writing a text file, the given Text will be written to the file, and the text content can optionally be appended to the end of the existing file. In the case of writing a binary file, the contents of the chosen Binary Data will be written to the file.
- Copy file
- Only applies to folder pickers. Copy a file within a previously picked folder. The Source path specifies an existing file to copy, e.g. "subfolder/file1.txt". The Destination path specifies where to create a copy; this will either create a new file if it doesn't exist, or overwrite an existing file if it already exists. The File tag is optional and allows identifying when the copy operation completes or fails with the On file operation complete/error triggers.
- Create folder
- Only applies to folder pickers. Create a subfolder within a previously picked folder. The Folder path specifies the folder to create. This can refer to multiple subfolders which will all be created, e.g. "subfolder/otherfolder". The File tag is optional and allows identifying when the folder creation operation completes or fails with the On file operation complete/error triggers.
- Delete
- Only applies to folder pickers. Delete a file or folder within a previously picked folder. The Folder path specifies the file or folder to delete, e.g. "subfolder/file1.txt" or "subfolder". The Recursive option applies only when Folder path identifies a folder: if enabled it will delete all files and folders within the identified folder as well as the folder itself, but if disabled it will only successfully delete the folder if it is already empty. The File tag is optional and allows identifying when the delete operation completes or fails with the On file operation complete/error triggers.
- List content
- Only applies to folder pickers. Retrieves a list of all files and folders within a previously picked folder. The Folder path identifies a subfolder to list the contents for, or can be left empty to list the contents of the originally picked folder. The File tag is optional and allows identifying when the listing operation completes or fails with the On file operation complete/error triggers. Once completed, the available files and folders can be accessed with the FileCount, FileNameAt, FolderCount and FolderNameAt expressions.
File system expressions
- FileCount
- FileNameAt(index)
- Retrieve the number and filenames of available files. This can be used after a save file picker to identify the chosen saved filename (which is just one file), after an open file picker to identify the available filenames (which can be multiple filenames if the Multiple option was enabled, otherwise it is just one file), or after the List content action for listing the contents of a folder.
- FolderCount
- FolderNameAt(index)
- Retrieve the number and names of available subfolders after the List content action for listing the contents of a folder.
- FileText
- After a Read text file action completes successfully, the contents of the read file.
- FileTag
- In a file system operation trigger such as On any file operation complete, this returns the file tag of the associated file operation.