Lua VFS

From Spring

Development < Lua Scripting < Lua VFS

Modes

VFS.RAW

VFS.MOD New in version 104.0

VFS.MAP New in version 104.0

VFS.BASE New in version 104.0

VFS.MENU New in version 104.0

VFS.ZIP

VFS.RAW_FIRST

VFS.ZIP_FIRST

VFS.RAW_ONLY (same as VFS.RAW)

VFS.ZIP_ONLY (same as VFS.ZIP)

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.

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

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 in version 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 in version 98.0

 ( ) -> {
  [1] = string mapName, ...
}

VFS.GetGames New in version 98.0

 ( ) -> {
  [1] = string gameName, ...
}

VFS.GetAllArchives New in version 98.0

 ( ) -> {
  [1] = string archiveName, ...
}

VFS.GetLoadedArchives New in version 105.0

 ( ) -> {
  [1] = string archiveName, ...
}

VFS.GetArchivePath New in version 105.0

 ( string archiveName ) -> string archivePathOnDisk

VFS.GetNameFromRapidTag New in version 105.0

 ( string rapidTag ) -> string archiveName

VFS.HasArchive New in version 98.0

 ( string archiveName ) -> boolean

VFS.GetArchiveInfo New in version 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 in version 98.0

 ( string archiveName ) -> string singleArchiveChecksum, string completeArchiveChecksum

VFS.GetArchiveDependencies New in version 98.0

 ( string archiveName ) -> { 
   [1] = string archiveName, ... 
 }

VFS.GetArchiveReplaces New in version 98.0

 ( string archiveName ) -> { 
   [1] = string archiveName, ... 
 }

VFS.DownloadArchive New in version 101.0

 ( name, category ) -> nil

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

VFS.AbortDownload New in version 104.0

 ( id ) -> boolean foundAndRemoved

Additional functions are available as part of the 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"