Installing the Plugin

1. Add the plugin to the AGK IDE. Copy the LzmaPlugin folder of this project into the "Tier 1\Compiler\Plugins" folder where App Game Kit 2 is installed on your system.
2. Copy the 7za.dll file from one of the example project folders into your project folder.
3. If you want to be able to debug your game while using this plugin, copy the 7za.dll file into the "Tier 1\Compiler\interpreters" folder where App Game Kit 2 is installed on your system.

The AGK site has a complete guide to creating, installing, and using AGK plugins that you might find useful if you're new to them.

Using the Plugin

Using a 7-Zip archive for your data with AppGameKit is not as easy as archiving a bunch of PNG and WAV files into a .7z file and reading them from the archive. AppGameKit cannot load some these file formats directly from memory and they must come from a file on your system. However, AppGameKit does provide the ability to load and save these types of data using its own memblock formats which is what this plugin uses for storage.

To create an archive, you'll need to write AppGameKit code that opens the archive in write mode and then uses the SetItemFrom commands to store data using memblocks. The plugin has commands that are specific for images, sounds, object meshes, strings, and files which handle all of the memblock related code for you.

Be sure to remove or comment out the code used to create the archive when you're done because the release version of your game should not include it.

Once the archive is created, use the GetItem commands to retrieve the data from it. Again, data can be extracted directly into a memblock or the plugin also provides commands to extract images, sounds, object meshes, and strings directly into AppGameKit.

It is also possible to stora a file and extract it to your game's write folder using the ExtractItemToFile command. The last parameter is a flag that when set tells the plugin to attempt to delete the extracted file when the game closes and the plugin is unloaded. This can be useful if you want to store music OGG files in an archive and temporarily extract them while your game is running. Remember though that extraction can take some time and deleting extracted files is not guaranteed to work.

Example

There's also an example project in the code that demonstrates more than this simple example.

#import_plugin LzmaPlugin As archive // Import the plugin into the your project

#constant ARCHIVENAME	"archive.bin"
#constant PASSWORD	"mypassword"

// Create the archive.
archiveID as integer
archiveID = archive.OpenToWrite(ARCHIVENAME, PASSWORD)
if archiveID
    archive.SetItemFromImageFile(archiveID, "star.image", "star.png")
endif
archive.Close(archiveID)

// Read from the archive
imageID as integer
archiveID = archive.OpenToRead(ARCHIVENAME, PASSWORD)
if archiveID
	imageID = archive.GetItemAsImage(archiveID, "star.image")
endif
archive.Close(archiveID)