**(save-game: // [[harlowe:String|String]], [ String ]//) -> //[[harlowe:Boolean|boolean]]//**

This macro saves the current game's state in browser storage, in the given save slot,
and including a special filename. It can then be restored using [[harlowe:load-game|(load-game:)]].

=== Rationale: ===

Many web games use browser cookies to save the player's place in the game.
Twine allows you to save the game, including all of the variables that were [[harlowe:set|(set:)]]
or [[harlowe:put|(put:)]], and the passages the player visited, to the player's browser storage.

(save-game:) is a single operation that can be used as often or as little as you
want to. You can include it on every page; You can put it at the start of each "chapter";
You can put it inside a [[harlowe:link|(link:)]] hook, such as

<code>
{(link:"Save game")[
  (if:(save-game:"Slot A"))[
    Game saved!
  ](else: )[
    Sorry, I couldn't save your game.
  ]
]}
</code>
and let the player choose when to save.

=== Details: ===

(save-game:)'s first [[harlowe:string|string]] is a slot name in which to store the game. You can have as many slots
as you like. If you only need one slot, you can just call it, say, ''%%"A"%%'', and use ''%%(save-game:"A")%%''.
You can tie them to a name the player gives, such as ''%%(save-game: $playerName)%%'', if multiple players
are likely to play this game - at an exhibition, for instance.

Giving the saved game a file name is optional, but allows that name to be displayed by finding it in the
$Saves [[harlowe:datamap|datamap]]. This can be combined with a [[harlowe:load-game|(load-game:)]][[harlowe:link|(link:)]] to clue the players into the save's contents:

<code>
(link: "Load game: " + ("Slot 1") of Saves)[
  (load-game: "Slot 1")
]
</code>
(save-game:) evaluates to a [[harlowe:boolean|boolean]] - true if the game was indeed saved, and false if the browser prevented
it (because they're using private browsing, their browser's storage is full, or some other reason).
Since there's always a possibility of a save failing, you should use [[harlowe:if|(if:)]] and [[harlowe:else|(else:)]] with (save-game:)
to display an apology message in the event that it returns false (as seen above).

=== See also: ===

[[harlowe:load-game|(load-game:)]], [[harlowe:saved-games|(saved-games:)]]