Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The BinarySerialize function is a function which can save a binary file representing an instance of an object. This function is similar to FlatRedBall.IO.FileManager.XmlSerialize, but the resulting file is a binary file rather than a text XML file.
Binary files have the following benefits:
Binary files cannot be opened and edited as easily as XML files. This makes binary serialization a good choice for files which you do not want users to be able to modify.
Binary files are often smaller on disk than XML files. For smaller files this doesn't matter much, but it can have a large impact on file size when dealing with larger files.
Binary files can be faster to load.
Binary files have the following downsides:
Binary files are more difficult to debug - you can't simply look at the file and identify issues.
Binary serialization is not supported on every platform.
Binary files created on one platform may not be usable on another platform.
Binary files do not use a standard structure, therefore any area where the binary file is needed requires a custom loader. Most non-C# technology includes XML parsing libraries.
Any type that is run through the BinarySerialize function must be marked as serializable. For example:
However, the
The GetUserFolder method returns a string which can be used to save and load files in the user folder. To use this, the InitializeUserFolder method must be called first. The return value for GetUserFolder depends on the platform that the call is made on; however, it can be used on any platform with most methods that access the file system through the FileManager.
For an example on how to use GetUserFolder, see the InitializeUserFolder article.
The SaveEmbeddedResource method can be used to save a file which has been compiled as an EmeddedResource to disk. This method is useful for PC tools, especially Gum plugins.
The following will save the redball.bmp image to the given target directory assuming it exists in the current assembly:
The FileManager provides methods and properties commonly used when working with files on the hard disk.
Functions which access files on the file system may fail if the operating system is case sensitive (as is the case for Android and iOS).
The iOS operating system is case sensitive; however the simulator is not case sensitive by default - this can make testing more difficult. For information on how to make the simulator run in case sensitive mode, see this link: http://wjlafrance.net/post/44870455348/making-the-ios-simulator-case-sensitive
The CloneObject method performs a deep clone of an object. This uses XML serialization so the object that is to be cloned must be XML serializable. This can be used to clone any "save" object, but should not be used on runtime objects such as Sprite.
Example of "save" objects include:
Engine objects with the name "Save" at the end like SpriteSave, SceneSave, and AnimationChainSave
Instances of objects that come from CSVs
Objects which do not contain references to other objects, like Vector3. Although these may not technically be considered "save" objects, they can be properly cloned using CloneObject.
The InitializeUserFolder is a method which prepares a user-specific storage area for saving and loading game content. The user folder can contain information such as game settings (audio volume), progress (how far the player has made it through the game), and debug information (such as call stacks if the application crashes).
The user folder has both read and write access on every device, and using the user folder is the preferred way to save data when using FlatRedBall as it enables cross-platform IO support.
The InitializeUserFolder method must be called before any other methods which use the user folder. This method initializes the user folder, gets its location, and saves a text file.
The FileManager's RelativeDirectory is a directory that is used as the directory that file loading is performed relative to.
For example, let's say the FileManager's RelativeDirectory is
In this case any file-related FRB call will result in FlatRedBall looking in this directory for files. Therefore, we could create a Sprite as follows:
This would result in the engine looking for the following file:
Generated Glue code assumes that the RelativeDirectory is the directory of the .exe file. Therefore, if your code ever changes the RelativeDirectory and you are using Glue, you should change the RelativeDirectory back to its old value. See below on an example of how to preserve RelativeDirectory.
Virtually any FlatRedBall call which access information off of the disk will use FileManager.RelativeDirectory. For example the following calls will use the RelativeDirectory when relative paths:
Any FlatRedBall Save Class's FromFile and Save methods
The RelativeDirectory defaults to the directory of your executable if your application is running on the PC (as opposed to Silverlight or the Xbox 360). This file is determined when execution first starts. In other words, running your application in a different folder or on a different machine will result in a different RelativeDirectory at startup. This keeps file loading portable.
In some cases you may want to change the FileManager's RelativeDirectory property; however, there are some restrictions when you do this:
The RelativeDirectory must always be an absolute path.
The RelativeDirectory should preferably be relative to the location of your executable.
These two requirements might seem contradictory - how can you guarantee that RelativeDirectory stays relative to your .exe, but at the same time achieve that by setting an absolute path?
The answer is to use the old RelativeDirectory value when setting a new RelativeDirectory.
Let's say that you want to set the RelativeDirectory to your "Content" folder, as you plan on doing all loading from that folder. To do this, you'll simply want to append "Content\" to your RelativeDirectory as follows:
This means that your program will use the "Content" folder for all of its loading logic; however, your file access code will remain relative.
You should NOT do this:
If you do this then your game will break if you decide to move it to another computer, if you send it to a friend, or if you switch to a different platform like the Xbox 360 or Silverlight.
Many file formats assume that contained references are relative to the file itself. For example, consider a .scnx file which references "redball.bmp". By default if you try to load "redball.bmp" your program will attempt to look for a redball.bmp file in the same folder as the .exe. If you are writing code which will load objects relative to another file, you may want to temporarily set the RelativeDirectory value, then change it back after you're finished.
For example, let's say that MySaveClass has a list of Sprites that it will load. The code to load this might be as follows:
The FileManager supports the use of the "../" string which indicates to "move up one directory". You can change the RelativeDirectory by appending "../" at the end as follows:
You can also use the backslash:
This sill result in the RelativeDirectory moving up one directory. Keep in mind that RelativeDorectory must always be absolute, so the following is not valid:
Also, it is not recommended that you use "../" to navigate up any higher than the starting RelativeDirectory as this will keep your application from being portable.
The "./" string represents "this directory". This string should not be used when dealing with the RelativeDirectory property because it is a string that is reserved by FlatRedBall to indicate an absolute path on non-PC platforms.
The "./" can be used to indicate an absolute path if you would like to prevent the FileManager from making the file absolute. In other words, this operation would use the RelativeDirectory:
while on non-PC platforms, this is absolute:
We strongly recommend not using absolute paths like this because they keep your application from being portable to the PC versions of FlatRedBall.
The XmlDeserialize function is a function that can load a XML file and create a runtime object out of it. You must have an object that matches a given XML's format to properly deserialize an XML into an instance you can use at runtime. The XmlDeserialize method uses System.Xml.Serialization.XmlSerializer internally, but this provides a convenient way to deserialize objects with one call. XmlDeserialize uses the FileManager's RelativeDirectory when given relative paths to deserialize.
For an example on how XmlDeserialize works, see XmlSerialize: http://flatredball.com/documentation/api/flatredball/flatredball-io/flatredball-io-filemanager/flatredball-io-filemanager-xmlserialize/
Introduction The Standardize method is used to convert file names to a standard format. By default Standardize performs the following modifications to a file name:
It is converted to lower case
Backslashes are converted to forward slashes
Relative files are made absolute
Standardize is useful because it allows string comparison between files.
GetAllFilesInDirectory is a method which can be used to get all files in a given directory and its sub-directories. The overloads for this method provide constraints such as the number of levels deep to search, and limitations on the file types.
The following call:
is equivalent to calling:
An empty string as the fileType will return all contained files.
The following code creates a ListBox to display all .jpg files which exist in the c:\Projects directory. If you do not have this directory on your computer, you will need to change the directory variable. Keep in mind that if the depth variable is large, or if the argument directory has a lot of files and sub-directories, this call can take a long time to execute. Add the following using statements:
Add the following to Initialize after initializing FlatRedBall:
The SaveText function is a function that can be used to easily save the contents of a string to a .txt file. This function will overwrite previously-created .txt files if an existing file name is passed, so be careful calling this method.
The following code creates a string, saves it to a .txt file, then opens that file.
The UserApplicationDataForThisApplication property gives you an absolute path that you can use in your application to save information for the given application. Examples of information you may want to save are:
Settings for a tool (such as window size)
Debug information
Save data (such as the user's profile)
If your game/application uses an installer to install itself to Program Files or "Program Files (x86)" (on Windows 7) then you will not be able to save files in the same location as the .exe. This is a security feature of later versions of Windows.
The UserApplicationDataForThisApplication gives you a folder which can be saved to without security issues.
The following saves a file called "myFile.txt" which contains the text "Hello World" to the application data folder.
As mentioned above, game data can be saved to disk as XML files. For example, the following class could be used to save information about the user's progress:
A screen can be modified to save and load the project:
If the path of the file to save does not exist, then the XmlSerialize method will attempt to create the appropriate directory before saving the XML file.
The XmlSerialize and XmlDeserialize methods are methods which can be used to easily convert a class to an XML file, or an XML file back into an instance of a given type. XmlSerialize and XmlDeserialize are often used to save and load game data, such as player progress. Internally the FileManager uses the System.Xml.Serialization.XmlSerializer for serialization and deserialization. This means that any XML file created by the FileManager can be deserialized using the XmlSerializer if FlatRedBall is not available. Similarly, FlatRedBall can deserialize files created in other applications which use the XmlSerializer to save XML files. XmlSerialize uses the when given relative paths to serialize.
The XmlSerialize internally uses and classes. This means that all XML attributes (such as ) will apply normally.
The FileManager uses the . Therefore if the type cannot be serialized by the internal XmlSerializer then the FileManager.XmlSerialize will throw an exception. For information on this error, .
- Discusses the "Save" class coding pattern commonly used to save game data.