Qrow: 1 revision imported

2025-11-13T01:50:58Z

1 revision imported

← Older revision	Revision as of 18:50, 12 November 2025
(No difference)

interwiki3>Beherith: /* Files */

2022-08-08T09:53:38Z

Files

New page

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

= Overview =

Although Spring can access the filesystem directly (via os module) it is more common that you
would want to access files included with your game or Spring. Trouble is, most of these files are
compressed into archives (.sdz/.sd7) so random access would generally be a difficult procedure.
Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.

The VFS module doesn't simply open archives though. What it does is map your game files, game
dependencies and Spring content onto a virtual file tree. All archives start from the 'roots' of the tree
and share the same virtual space, meaning that if two or more archives contain the same resource
file name the resources overlap and only one of the files will be retrieved. Overlapping directories
on the other hand are merged so the resulting virtual directory contains the contents of both. Here is
an example of how this works:

'''Archive 1 (games/mygame.sd7)'''

textures 
|__ texture1.png 
models 
|__ model1.mdl 

'''Archive 2 (base/springcontent.sdz'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 

'''VFS'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 
models 
|__ model1.mdl 

This raises the question: If both archives have a texture1.png then which texture1.png is retreived
via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on
modes below). Generally however, each archive loaded overrides any archives loaded
before it. The standard order of loading (from first to last) is:

# The main Spring/ game directory.
# The automatic dependencies springcontent.sdz and maphelper.sdz.
# Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed.
# Your mod archive.

= Modes =

These modes are constants passed to VFS.Include() and friends to control the order that archives are
searched for a given file. They are case-sensitive.

'''VFS.RAW''' Only select uncompressed files.

'''VFS.MOD''' {{new|104.0}}

'''VFS.MAP''' {{new|104.0}}

'''VFS.BASE''' {{new|104.0}}

'''VFS.MENU''' {{new|104.0}}

'''VFS.ZIP''' Only select compressed files (.sdz,.sd7).

'''VFS.RAW_FIRST''' Try uncompressed files first, then compressed.

'''VFS.ZIP_FIRST''' Try compressed files first, then uncompressed.

'''VFS.RAW_ONLY''' (Deprecated. Same as VFS.RAW)

'''VFS.ZIP_ONLY''' (Deprecated. Same as VFS.ZIP.)

See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

= Files =
'''VFS.Include''' (if enviroment=nil then use current one)
( string "filename" [, table enviroment = nil [, number mode ] ] ) ->
The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left nil to preserve Springs default.

If nil then the env will be _G (global environment) If the optional env argument is provided any non-local variables and functions defined in
filename.lua are then accessable via env or _G. Vise-versa, any variables defined in env prior to
passing to VFS.Include are available to code in the included file. Code running in filename.lua will
see the contents of env in place of the normal _G environment. 

This loads and compiles the lua code from a file in the VFS. The path is relative to the main Spring directory, e.g. VFS.Include('LuaUI/includes/filename.lua', nil, [vfsmode]) 

VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (=location) from which to include files.

'''VFS.LoadFile'''
( string "filename" [, number mode ] ) -> nil | string data

This is used for loading raw text data, as it will not execute the file, like VFS.Include does, just returns a string of the file contents.

'''VFS.FileExists'''
( string "filename" [, number mode ] ) -> boolean
example usage: if VFS.FileExists("maps/Castles.sdz") then ... end 

'''VFS.DirList'''
( string "directory" [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string filename, ... }
'''VFS.SubDirs'''
( string "directory", [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string subdir1, ... }

'''VFS.GetAvailableAIs'''
( [ string gameName] [, string mapName ] )
-> { ai1, ai2, ... }
Gets a list of all Spring AIs. The optional gameName and mapName parameters can be used to include game/map specific LuaAIs in the list.

'''VFS.UseArchive''' unsynced only!
( string "filename" [, number mode ], lua_function [, arg1 [,arg2 ]] )
-> result1,result2,... of the given lua_function
Loads an archive '''temporarely''' in the VFS and then runs the given lua_function, which can make usage of the files in the archive.

'''VFS.MapArchive''' unsynced only!
( string "filename/modname of archive", [string checksum of archive] )
-> bool
Permanently loads an archive into the VFS (to load zipped music collections etc.). Does nothing if the archive is already loaded in the VFS (won't reload even if there are changes made to the archive). If checksum is given it checks if the to be loaded file is correct, if not then it won't load it and return false.

'''VFS.UnmapArchive''' unsynced only! available in 98.0
( string "filename/modname of archive")
-> bool
Removes an already loaded archive (see VFS.MapArchive)

'''VFS.CompressFolder''' unsynced only!
( string "folderPath" [, string "archiveType" ] [, string "compressedFilePath" ] [, bool includeFolder ] [, number mode ] ) -> nil

Compresses the specified folder. archiveType defines the compression type which can currently be only "zip" includeFolder specifies whether the archive should have the specified folder as root (defaults to false) 

'''VFS.GetFileAbsolutePath''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> absPath | nil

'''VFS.GetArchiveContainingFile''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> archiveNameWithVersion | nil

= Generic hash =
'''VFS.CalculateHash''' {{new|101.0}}
( string input, number hashType)
-> string md5hash

Calculates hash (in base64 form) of a given string (with md5 support initially). Note supplying 0 (MD5) as hashType is mandatory

= Archives =

'''VFS.GetMaps''' {{new|98.0}}
( ) -> {
[1] = string mapName, ...
}

'''VFS.GetGames''' {{new|98.0}}
( ) -> {
[1] = string gameName, ...
}

'''VFS.GetAllArchives''' {{new|98.0}}
( ) -> {
[1] = string archiveName, ...
}

'''VFS.GetLoadedArchives''' {{new|105.0}}
( ) -> {
[1] = string archiveName, ...
}

'''VFS.GetArchivePath''' {{new|105.0}}
( string archiveName ) -> string archivePathOnDisk

'''VFS.GetNameFromRapidTag''' {{new|105.0}}
( string rapidTag ) -> string archiveName

'''VFS.HasArchive''' {{new|98.0}}
( string archiveName ) -> boolean

'''VFS.GetArchiveInfo''' {{new|98.0}}
( string archiveName ) - >
{
name = string,
shortname = string,
version = string,
mutator = string,
game = string,
shortgame = string,
description = string,
mapfile = string,
modtype = number,
}
modtype values:1=primary, 0=hidden, 3=map

'''VFS.GetArchiveChecksum''' {{new|98.0}}
( string archiveName ) -> string singleArchiveChecksum, string completeArchiveChecksum

'''VFS.GetArchiveDependencies''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.GetArchiveReplaces''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.DownloadArchive''' {{new|101.0}}
( name, category ) -> nil

Category must be one of: map, game, engine.

'''VFS.AbortDownload''' {{new|104.0}}
( id ) -> boolean foundAndRemoved

Additional functions are available as part of the [[Lua_UnsyncedCtrl#.28Virtual-.29FileSystem|unsynced ctrl]].

= Packing =
The Pack- and Unpack-functions are used to convert numbers->strings and strings->numbers.
So you can read a binary file and then convert the received strings back to numbers and the other way around. Also you can use it in combination with the SendLuaXYZMsg-functions.

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

'''VFS.PackX( number arg1, number arg2, number arg3, ... )''' -> string

'''VFS.PackX( {[1]=number,[2]=number,..} )''' -> string

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

'''VFS.UnpackX( string "binary" [, number position = 1] [, number count] )'''
-> number | table { [1]=number,[2]=number,.. }

= Zlib =
'''VFS.ZlibCompress''' unsynced only!
( string "uncompressedStr" )
-> nil | string "compressedStr"

'''VFS.ZlibDecompress''' available in synced, too!
( string "compressedStr" [, number uncompressed size = 65500] )
-> nil | string "uncompressedStr"

[[category: Lua]]

Lua VFS - Revision history

Qrow: 1 revision imported

interwiki3>Beherith: /* Files */