Lua VFS - Revision history

Beherith: /* Files */

2022-08-08T09:53:38Z

Files

← Older revision		Revision as of 10:53, 8 August 2022
Line 91:		Line 91:
	'''VFS.LoadFile'''		'''VFS.LoadFile'''
	( string "filename" [, number mode ] ) -> nil \| string data		( 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'''		'''VFS.FileExists'''
	( string "filename" [, number mode ] ) -> boolean		( string "filename" [, number mode ] ) -> boolean

Beherith: /* Files */

2022-01-14T11:17:23Z

Files

← Older revision		Revision as of 12:17, 14 January 2022
Line 78:		Line 78:
	'''VFS.Include''' <span class=note>(if enviroment=nil then use current one)</span>		'''VFS.Include''' <span class=note>(if enviroment=nil then use current one)</span>
	( string "filename" [, table enviroment = nil [, number mode ] ] ) ->		( string "filename" [, table enviroment = nil [, number mode ] ] ) ->
	<span class=note>The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left nil to preserve Springs default.</span>		<span class=note>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. </span>

			<span class=note>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]) </span>

	<span class=note>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.</span>		<span class=note>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.</span>

Beherith at 11:13, 14 January 2022

2022-01-14T11:13:41Z

← Older revision		Revision as of 12:13, 14 January 2022
Line 1:		Line 1:
	[[Engine_Development\|Development]] < [[Lua_Scripting\|Lua Scripting]] < {{FULLPAGENAME}}		[[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<br>
			\|__ texture1.png<br>
			models<br>
			\|__ model1.mdl<br>

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

			textures<br>
			\|__ texture1.png<br>
			\|__ texture2.png<br>
			\|__ texture3.png<br>

			'''VFS'''

			textures<br>
			\|__ texture1.png<br>
			\|__ texture2.png<br>
			\|__ texture3.png<br>
			models<br>
			\|__ model1.mdl<br>

			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 =		= Modes =

Beherith: /* Modes */

2022-01-14T11:05:32Z

Modes

← Older revision		Revision as of 12:05, 14 January 2022
Line 2:		Line 2:

	= Modes =		= Modes =
	'''VFS.RAW'''
			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.MOD''' {{new\|104.0}}
Line 12:		Line 16:
	'''VFS.MENU''' {{new\|104.0}}		'''VFS.MENU''' {{new\|104.0}}

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

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

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

	'''VFS.~~ZIP_FIRST~~'''		'''VFS.RAW_ONLY''' <font color=#55ee99>(Deprecated. Same as VFS.RAW)</font>

	'''VFS.~~RAW_ONLY~~''' <font color=#55ee99>(~~same~~ as VFS.~~RAW~~)</font>		'''VFS.ZIP_ONLY''' <font color=#55ee99>(Deprecated. Same as VFS.ZIP.)</font>

	~~'''VFS~~.~~ZIP_ONLY''' <font color=#55ee99>(same as VFS~~.~~ZIP)</font>~~		See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

	= Files =		= Files =

Gajop: Add two additional functions that exist in develop/maintenance branches.

2019-04-21T04:00:11Z

Add two additional functions that exist in develop/maintenance branches.

@@ Line 96: / Line 96: @@
     [1] = string archiveName, ...
+  }
 '''VFS.HasArchive''' {{new|98.0}}

Gajop: /* Files */

2019-04-05T23:26:09Z

Files

← Older revision		Revision as of 00:26, 6 April 2019
Line 66:		Line 66:

	<span class=note>Compresses the specified folder. <br>archiveType defines the compression type which can currently be only "zip" <br>includeFolder specifies whether the archive should have the specified folder as root (defaults to false) </span>		<span class=note>Compresses the specified folder. <br>archiveType defines the compression type which can currently be only "zip" <br>includeFolder specifies whether the archive should have the specified folder as root (defaults to false) </span>

			'''VFS.GetFileAbsolutePath''' <span class=warning>unsynced only! available in 105.0</span>
			( string "filename" [, number mode ] ) -> absPath \| nil

			'''VFS.GetArchiveContainingFile''' <span class=warning>unsynced only! available in 105.0</span>
			( string "filename" [, number mode ] ) -> archiveNameWithVersion \| nil

	= Generic hash =		= Generic hash =

Silentwings: /* Files */ add docs for args of VFS.Include

2018-11-24T11:14:10Z

Files: add docs for args of VFS.Include

← Older revision		Revision as of 12:14, 24 November 2018
Line 25:		Line 25:
	'''VFS.Include''' <span class=note>(if enviroment=nil then use current one)</span>		'''VFS.Include''' <span class=note>(if enviroment=nil then use current one)</span>
	( string "filename" [, table enviroment = nil [, number mode ] ] ) ->		( string "filename" [, table enviroment = nil [, number mode ] ] ) ->
			<span class=note>The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left nil to preserve Springs default.</span>

			<span class=note>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.</span>

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

Ivand at 00:00, 26 October 2018

2018-10-26T00:00:35Z

← Older revision		Revision as of 01:00, 26 October 2018
Line 63:		Line 63:
	<span class=note>Compresses the specified folder. <br>archiveType defines the compression type which can currently be only "zip" <br>includeFolder specifies whether the archive should have the specified folder as root (defaults to false) </span>		<span class=note>Compresses the specified folder. <br>archiveType defines the compression type which can currently be only "zip" <br>includeFolder specifies whether the archive should have the specified folder as root (defaults to false) </span>

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

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

	= Archives =		= Archives =

Flozi: /* Archives */ 104.0 - Add VFS.AbortDownload(id) - returns whether the download was found&removed from the queue

2017-12-18T21:01:14Z

Archives: 104.0 - Add VFS.AbortDownload(id) - returns whether the download was found&removed from the queue

← Older revision		Revision as of 22:01, 18 December 2017
Line 121:		Line 121:

	Category must be one of: map, game, engine.		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]].		Additional functions are available as part of the [[Lua_UnsyncedCtrl#.28Virtual-.29FileSystem\|unsynced ctrl]].

Flozi: /* Modes */ 104.0 - Implement VFS modes - VFS.MOD, VFS.MAP & VFS.BASE now actually work. Added VFS.MENU

2017-12-18T20:57:40Z

Modes: 104.0 - Implement VFS modes - VFS.MOD, VFS.MAP & VFS.BASE now actually work. Added VFS.MENU

← Older revision		Revision as of 21:57, 18 December 2017
Line 2:		Line 2:

	= Modes =		= Modes =
	'''VFS.RAW'''~~<br>~~		'''VFS.RAW'''
	'''VFS.MOD''' ~~<font color=red>(unimplemented, acts like VFS~~.~~ZIP)</font><br>~~
	'''VFS.MAP''' ~~<font color=red>(unimplemented, acts like VFS~~.~~ZIP)</font><br>~~		'''VFS.MOD''' {{new\|104.0}}
	'''VFS.BASE''' ~~<font color=red>(unimplemented, acts like~~ VFS.~~ZIP)</font><br>~~
	'''VFS.ZIP'''~~<br>~~		'''VFS.MAP''' {{new\|104.0}}
	'''VFS.RAW_FIRST'''~~<br>~~
	'''VFS.ZIP_FIRST'''~~<br>~~		'''VFS.BASE''' {{new\|104.0}}
	'''VFS.RAW_ONLY''' <font color=#55ee99>(same as VFS.RAW)</font>~~<br>~~
	'''VFS.ZIP_ONLY''' <font color=#55ee99>(same as VFS.ZIP)</font~~><br~~>		'''VFS.MENU''' {{new\|104.0}}

			'''VFS.ZIP'''

			'''VFS.RAW_FIRST'''

			'''VFS.ZIP_FIRST'''

			'''VFS.RAW_ONLY''' <font color=#55ee99>(same as VFS.RAW)</font>

			'''VFS.ZIP_ONLY''' <font color=#55ee99>(same as VFS.ZIP)</font>

	= Files =		= Files =