Device: add SaveGame

docs/lua_api.rst

@@ -1411,6 +1411,50 @@ Represents a collection of resources that can be loaded in group.
 **has_loaded** (package) : bool
 	Returns whether the *package* has been loaded.
 
+SaveGame
+========
+
+Singleton to save and load savegames.
+
+**save** (filename, data) : Id
+	Starts saving *data* to *filename* asynchronously and returns its request id.
+	The function returns before the file has been written. Poll for completion
+	with ``SaveGame.status()``. *filename* must be a filename, not a path. *data*
+	must be a table with string keys. Values can be bool, number, string, table,
+	Vector3, Vector3Box, Matrix4x4 or Matrix4x4Box.
+
+**load** (filename) : Id
+	Starts loading *filename* asynchronously and returns its request id. The
+	function returns before the file has been read. Poll for completion with
+	``SaveGame.status()``. *filename* must be a filename, not a path. When the
+	request is done, the loaded table is returned in the ``data`` field of
+	``SaveGame.status()``.
+
+**status** (request) : table
+	Returns a table with the current status of *request*.
+
+	The returned table has the following fields:
+
+	* ``done``: Whether the request has finished.
+	* ``progress``: Completion progress in the [0; 1] range.
+	* ``data``: The loaded table. This field is present only for successful load requests.
+	* ``error``: One of `SaveError`_, or ``nil`` if the request is done and no error has occurred.
+
+**free** (request)
+	Frees the resources held by *request*. Call this after the request is done.
+	After this call, *request* is invalid.
+
+SaveError
+---------
+
+* ``INVALID_REQUEST``: The request id is invalid.
+* ``SAVE_DIR_UNSET``: ``save_dir`` is not configured.
+* ``MISSING``: The save file does not exist.
+* ``INVALID_FILENAME``: The filename is invalid.
+* ``IO_ERROR``: File read/write failed.
+* ``CORRUPTED``: Save data could not be parsed.
+* ``UNKNOWN``: The request failed for an unknown reason.
+
 SceneGraph
 ==========
 

docs/reference/boot_config.rst

@@ -1,6 +1,24 @@
 boot.config reference
 =====================
 
+Path templates
+--------------
+
+Some settings accept path templates. A path template is a path that may contain
+variables in the form ``$VARNAME``.
+
+Supported variables:
+
+* ``$DATE``: The local date in ``YYYY-MM-DD`` format.
+* ``$UTC_DATE``: The UTC date in ``YYYY-MM-DD`` format.
+* ``$TIME``: The local time in ``HH-MM-SS`` format.
+* ``$UTC_TIME``: The UTC time in ``HH-MM-SS`` format.
+* ``$USER_DATA``: The user data directory. On Android, this expands to the
+  activity internal data path.
+* ``$TMP``: The temporary directory.
+* ``$RANDOM``: An 8-character random string.
+* ``$OBB_PATH``: Android only. The activity OBB path.
+
 Generic configurations
 ----------------------
 
@@ -32,7 +50,6 @@ All configurations for a given *platform* are placed under a key named *platform
 	  }
 	}
 
-
 Renderer configurations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -65,3 +82,9 @@ Physics configurations
 	A value of 4 at 60 Hz means the physics simulation is allowed to simulate up to ~0.067 seconds (4/60) worth of physics per frame.
 	If one frame takes longer than ``max_substeps/step_frequency`` then physics will appear slowed down.
 
+Other settings
+~~~~~~~~~~~~~~
+
+``save_dir = $USER_DATA/mygame``
+    Sets the directory where save files will be stored. Setting the save
+    directory is mandatory if you plan to use the SaveGame system.

scripts/crown-launcher.lua

@@ -39,7 +39,9 @@ project ("crown-launcher")
 	configuration {}
 
 	files {
+		CROWN_DIR .. "src/core/date.cpp",
 		CROWN_DIR .. "src/core/debug/**.cpp",
+		CROWN_DIR .. "src/core/environment.cpp",
 		CROWN_DIR .. "src/core/error/**.cpp",
 		CROWN_DIR .. "src/core/filesystem/path.cpp",
 		CROWN_DIR .. "src/core/guid.cpp",
@@ -50,6 +52,7 @@ project ("crown-launcher")
 		CROWN_DIR .. "src/core/strings/dynamic_string.cpp",
 		CROWN_DIR .. "src/core/strings/string_id.cpp",
 		CROWN_DIR .. "src/core/thread/mutex.cpp",
+		CROWN_DIR .. "src/core/time.cpp",
 		CROWN_DIR .. "src/device/log.cpp",
 		CROWN_DIR .. "tools/launcher/launcher.cpp",
 	}

scripts/crown.lua

@@ -116,6 +116,7 @@ function crown_project(_name, _kind, _defines)
 			targetextension ".js"
 			linkoptions {
 				"-pthread",               -- https://emscripten.org/docs/porting/pthreads.html#compiling-with-pthreads-enabled
+				"-lidbfs.js",
 				"-lopenal",
 				"-s ABORTING_MALLOC=0",
 				"-s PTHREAD_POOL_SIZE=8",

src/core/date.cpp

@@ -4,6 +4,7 @@
  */
 
 #include "core/date.h"
+#include <stb_sprintf.h>
 
 #if CROWN_PLATFORM_WINDOWS
 	#ifndef WIN32_LEAN_AND_MEAN
@@ -18,82 +19,94 @@ namespace crown
 {
 namespace date
 {
-	void date(s32 &year, s32 &month, s32 &day)
+	void date(Date &date)
 	{
 #if CROWN_PLATFORM_WINDOWS
 		SYSTEMTIME now;
 		GetLocalTime(&now);
-		year  = now.wYear;
-		month = now.wMonth;
-		day   = now.wDay;
+		date.year  = now.wYear;
+		date.month = now.wMonth;
+		date.day   = now.wDay;
 #else
 		time_t t;
 		struct tm now;
 		::time(&t);
 		localtime_r(&t, &now);
-		year  = now.tm_year + 1900;
-		month = now.tm_mon + 1;
-		day   = now.tm_mday;
+		date.year  = now.tm_year + 1900;
+		date.month = now.tm_mon + 1;
+		date.day   = now.tm_mday;
 #endif
 	}
 
-	void utc_date(s32 &year, s32 &month, s32 &day)
+	void utc_date(Date &date)
 	{
 #if CROWN_PLATFORM_WINDOWS
 		SYSTEMTIME now;
 		GetSystemTime(&now);
-		year  = now.wYear;
-		month = now.wMonth;
-		day   = now.wDay;
+		date.year  = now.wYear;
+		date.month = now.wMonth;
+		date.day   = now.wDay;
 #else
 		time_t t;
 		struct tm now;
 		::time(&t);
 		gmtime_r(&t, &now);
-		year  = now.tm_year + 1900;
-		month = now.tm_mon + 1;
-		day   = now.tm_mday;
+		date.year  = now.tm_year + 1900;
+		date.month = now.tm_mon + 1;
+		date.day   = now.tm_mday;
 #endif
 	}
 
-	void time(s32 &hour, s32 &minutes, s32 &seconds)
+	void time(Time &time)
 	{
 #if CROWN_PLATFORM_WINDOWS
 		SYSTEMTIME now;
 		GetLocalTime(&now);
-		hour    = now.wHour;
-		minutes = now.wMinute;
-		seconds = now.wSecond;
+		time.hour    = now.wHour;
+		time.minutes = now.wMinute;
+		time.seconds = now.wSecond;
 #else
 		time_t t;
 		struct tm now;
 		::time(&t);
 		localtime_r(&t, &now);
-		hour    = now.tm_hour;
-		minutes = now.tm_min;
-		seconds = now.tm_sec;
+		time.hour    = now.tm_hour;
+		time.minutes = now.tm_min;
+		time.seconds = now.tm_sec;
 #endif
 	}
 
-	void utc_time(s32 &hour, s32 &minutes, s32 &seconds)
+	void utc_time(Time &time)
 	{
 #if CROWN_PLATFORM_WINDOWS
 		SYSTEMTIME now;
 		GetSystemTime(&now);
-		hour    = now.wHour;
-		minutes = now.wMinute;
-		seconds = now.wSecond;
+		time.hour    = now.wHour;
+		time.minutes = now.wMinute;
+		time.seconds = now.wSecond;
 #else
 		time_t t;
 		struct tm now;
 		::time(&t);
 		gmtime_r(&t, &now);
-		hour    = now.tm_hour;
-		minutes = now.tm_min;
-		seconds = now.tm_sec;
+		time.hour    = now.tm_hour;
+		time.minutes = now.tm_min;
+		time.seconds = now.tm_sec;
 #endif
 	}
 
+	const char *to_string(char *buf, u32 len, const Date &date)
+	{
+		stbsp_snprintf(buf, len, "%04d-%02d-%02d", date.year, date.month, date.day);
+		return buf;
+	}
+
+	const char *to_string(char *buf, u32 len, const Time &time)
+	{
+		stbsp_snprintf(buf, len, "%02d-%02d-%02d", time.hour, time.minutes, time.seconds);
+		return buf;
+	}
+
 } // namespace date
 
 } // namespace crown

src/core/date.h

@@ -11,17 +11,37 @@ namespace crown
 {
 namespace date
 {
+	struct Date
+	{
+		s32 year;
+		s32 month;
+		s32 day;
+	};
+
+	struct Time
+	{
+		s32 hour;
+		s32 minutes;
+		s32 seconds;
+	};
+
 	///
-	void date(s32 &year, s32 &month, s32 &day);
+	void date(Date &date);
 
 	///
-	void utc_date(s32 &year, s32 &month, s32 &day);
+	void utc_date(Date &date);
 
 	///
-	void time(s32 &hour, s32 &minutes, s32 &seconds);
+	void time(Time &time);
 
 	///
-	void utc_time(s32 &hour, s32 &minutes, s32 &seconds);
+	void utc_time(Time &time);
+
+	/// Formats @a date as YYYY-MM-DD.
+	const char *to_string(char *buf, u32 len, const Date &date);
+
+	/// Formats @a time as HH-MM-SS.
+	const char *to_string(char *buf, u32 len, const Time &time);
 
 } // namespace date