README
¶
gdata
A gamedata package that provides convenient cross-platform storage for games.
Some examples of such gamedata that you might want to store:
- Game settings
- Save states
- Replays
- Pluging/mods metadata
This package was made with Ebitengine in mind, but it should be usable with any kind of a game engine for Go.
Platforms supported:
- Windows (file system, AppData)
- Linux (file system, ~/.local/share)
- MacOS (file system, ~/.local/share)
- Android (file system, app data directory)
- Browser/wasm (local storage)
This library tries to use the most conventional app data folder for every platform.
It provides a simple key-value style API. It can be considered to be a platform-agnostic localStorage.
This package was part of my game development framework which I used in all of my Go-powered games. Now I'm feel like it's ready to become a part of the ecosystem.
Installation
go get github.com/quasilyte/gdata
Quick Start
package main
import (
"fmt"
"github.com/quasilyte/gdata"
)
func main() {
// m is a data manager; treat it as a connection to a filesystem.
m, err := gdata.Open(gdata.Config{
AppName: "my_game",
})
if err != nil {
panic(err)
}
if err := m.SaveItem("save.data", []byte("mydata")); err != nil {
panic(err)
}
result, err := m.LoadItem("save.data")
if err != nil {
panic(err)
}
fmt.Println("=>", string(result)) // "mydata"
fmt.Println("exists?", m.ItemExists("save.data")) // true
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// AppName is used as a part of the key used to store the game data.
//
// The exact effect depends on the platform, but generally it doesn't have
// to reflect the application name perfectly.
//
// You need to use the same AppName to make sure that the game can
// then load the previously saved data.
// If you want to separate the data, use suffixes: "app" and "app2" data
// will be stored completely independently.
//
// An empty app name is not allowed.
AppName string
}
Config affects the created gamedata manager behavior.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager implements the main gamedata operations. You can create a new manager by using Open function.
func Open ¶
Open attempts to create a gamedata manager.
There are various cases when it can fail and you need to be ready to handle that situation and run the game without the save states. For instance, on wasm platforms it's using a localStorage which can be disabled. In this case, a non-nil error will be returned and the game should continue without any attempts to load or save data.
One gamedata manager per game is enough. You need to pass it explicitely as a part of your game's context.
func (*Manager) DeleteItem ¶
DeleteItem removes the data associated with the itemKey.
Be careful with this function: it removes the data permanently. There is no way to undo it.
Trying to delete a non-existing itemKey is not an error.
The returned error is usually a file operation error.
func (*Manager) ItemExists ¶
ItemExists reports whether the itemKey was saved before. An existing key will result in a non-nil data being read with LoadItem().
func (*Manager) ItemPath ¶
ItemPath returns a unique itemKey path.
On platforms with filesystem storage, it's an absolute file path. On other platforms it just some unique resource identifier.
You can't treat it as a filesystem path unless you're knowing what you're doing. It's safe to use it for debugging and for things like map keys.
Note that ItemPath returns a potential item path, it doesn't care if the item actually exists or not. Use ItemExists() method first if you need to know whether this itemKey is used.
Source Files