Към съдържанието
wannacode

Запис и зареждане

Накратко: Записът е светът като текст „ключ=стойност“ с версия и контролна сума най-отдолу; зареждането чете и проверява всичко в локални променливи и пипа играта чак накрая, затова развален запис се отказва, без да я повреди.

Проблем

Играта, която забравя всичко

Играч е прекарал два часа в Сивия брод: взел е броня, убил е стража на мината, събрал е злато. Затваря терминала. На сутринта играта започва отначало и той не се връща. Запис и зареждане са това, което превръща играта от сесия в пътуване.

Задачата изглежда проста („запиши променливите във файл“), но стоят три въпроса:

  1. Какво се записва? Не кодът и не таблиците (предмети, врагове, умения: те са в играта). Записва се само това, което играта е променила: героят, ходът, картата, враговете, куестовете. Останалото се строи наново.
  2. Откъде зареждането знае, че файлът е добър? Файлът може да е на друга игра, от по-стара или по-нова версия, откъснат по средата или пипнат на ръка.
  3. Какво прави, когато не е добър? Не се срутва и не остава наполовина заредена.

Урокът строи малък свят (герой, торба, ход) и прекарва през него и трите въпроса: записът като текст, версия и контролна сума, зареждане, което първо чете и проверява, и шест развалени записа. После показва същото в истинската игра.

Идеята

Светът като текст: ключ=стойност

Записът е обикновен текст, ред по ред: ключ, знак за равно, стойност. Един ред е един факт. Така файлът се чете с очи, сравнява се с друг запис в редактор и не иска библиотека. Ето типовете на малкия свят: герой с торба, игра и грешка при записа.

class Slot {
  constructor(id, count) {
    this.id = id;
    this.count = count;
  }
}


class Hero {
  constructor(name, level, hp, gold, x, y) {
    this.name = name;
    this.level = level;
    this.hp = hp;
    this.gold = gold;
    this.x = x;
    this.y = y;
    this.inventory = [];
  }
}


class Game {
  constructor(hero, turn) {
    this.hero = hero;
    this.turn = turn;
  }
}


class SaveError extends Error {}

А ето записът. Най-отгоре са форматът и версията, после светът, а най-отдолу е контролната сума (за нея след малко):

const SAVE_FORMAT = "ARCANUM";
const SAVE_VERSION = 1;


// Сумата е от символите на всичко над нея; ако някой промени и една буква, тя не съвпада.
function checksum(text) {
  let sum = 0;
  for (let i = 0; i < text.length; i++) sum = (sum * 31 + text.charCodeAt(i)) % 1000000007;
  return sum;
}


// Празният списък се пише като тире: така редът не остава с празна стойност.
function joinOrDash(parts) {
  return parts.length === 0 ? "-" : parts.join(",");
}


function sign(body) {
  return body + "checksum=" + checksum(body) + "\n";
}


function saveGame(game) {
  const hero = game.hero;
  const lines = [];
  lines.push("format=" + SAVE_FORMAT);
  lines.push("version=" + SAVE_VERSION);
  lines.push("turn=" + game.turn);
  lines.push("hero.name=" + hero.name);
  lines.push("hero.level=" + hero.level);
  lines.push("hero.hp=" + hero.hp);
  lines.push("hero.gold=" + hero.gold);
  lines.push("hero.x=" + hero.x);
  lines.push("hero.y=" + hero.y);
  const bag = [];
  for (const slot of hero.inventory) bag.push(slot.id + ":" + slot.count);
  lines.push("hero.inventory=" + joinOrDash(bag));
  return sign(lines.join("\n") + "\n");
}

Торбата е един ред: предмет:брой, разделени със запетая. Празната торба се пише като тире: ред hero.inventory= с празна стойност би изглеждал като липсваща. Всеки ред се прави с ключ=стойност, всичките се слепват с нов ред, и накрая sign слага сумата. Програмата записва Ива и после същата игра с празна торба (само двата реда, които се променят):

const game = new Game(new Hero("Iva", 3, 27, 42, 5, 2), 212);
game.hero.inventory.push(new Slot("potion_heal", 2));
game.hero.inventory.push(new Slot("leather", 1));
process.stdout.write(saveGame(game));


game.hero.inventory.length = 0;
const again = saveGame(game).split("\n");
console.log(again[9]);
console.log(again[10]);
Изход
format=ARCANUM
version=1
turn=212
hero.name=Iva
hero.level=3
hero.hp=27
hero.gold=42
hero.x=5
hero.y=2
hero.inventory=potion_heal:2,leather:1
checksum=624337035
hero.inventory=-
checksum=126903799

Втората сума е съвсем друга, макар да е променен един ред: това е целта ѝ.

По-точно, за любопитните

Какво канонът записва отгоре на нашия свят: семето и състоянието на генератора (seed, rng, ids), така че след зареждане зарчетата да следват същата редица; нивата (три карти, ред по ред, с видяното и украсата); враговете с живот, състояние и ефекти; куестовете и флаговете. Това не са таблиците с предмети и врагове: те са в играта и записът пази само id (potion_heal:2), а не целия предмет.

Какво не се записва, защото се смята наново: показателите със слоевете им (база, екипировка, ефекти), полето на видимост (след зареждане играта вика computeFov) и всичко, което се строи от таблиците. По-малко в записа значи по-малко места за грешка.

Идеята

Версия и контролна сума

Два реда пазят записа от неприятни изненади.

Версията (version=1) казва кой вариант на формата е писал файла. Играта ще се промени: ще има мана, ще има нови редове. Старата игра, която прочете нов запис, не бива да гадае; и новата, която прочете стар, трябва или да знае как, или да откаже ясно. Затова версията е втори ред и се проверява преди всичко друго, освен заглавието.

Контролната сума (checksum=...) е едно число от всички редове над нея. Ето я цялата:

// Сумата е от символите на всичко над нея; ако някой промени и една буква, тя не съвпада.
function checksum(text) {
  let sum = 0;
  for (let i = 0; i < text.length; i++) sum = (sum * 31 + text.charCodeAt(i)) % 1000000007;
  return sum;
}

Върви по знаците на текста: сумата се умножава по 31 и се добавя кодът на знака, а остатъкът от 1000000007 я пази малка. Умножението е важно. Ако само събираше кодовете, „ab“ и „ba“ щяха да са едно число. Ето какво дава това:

// Сумата е от символите на всичко над нея; ако някой промени и една буква, тя не съвпада.
function checksum(text) {
  let sum = 0;
  for (let i = 0; i < text.length; i++) sum = (sum * 31 + text.charCodeAt(i)) % 1000000007;
  return sum;
}


console.log(checksum("ab"));
console.log(checksum("ba"));
Отговор

Записът е готов, когато сумата на всичко над последния ред е написана най-отдолу. Който промени един знак, ще види сумата да не съвпада.

Числата в JavaScript са double, но sum * 31 е под 2^53 (до около 31 · 10^9), затова сметката е точна. charCodeAt(i) е кодът на знака.
// Празният списък се пише като тире: така редът не остава с празна стойност.
function joinOrDash(parts) {
  return parts.length === 0 ? "" : parts.join(",");
}

Идеята

Зареждане: първо четеш, после пипаш

Зареждането е огледалото на записа и има едно правило: докато не е прочетено и проверено всичко, играта не се пипа. Всичко се чете в локални променливи, а присвояването към играта е последното нещо в метода.

Първо проверките. readValues взема текста и връща таблица ключ → стойност, а при всяко нередно нещо хвърля SaveError със съобщението за играча:

// Само цифри, най-много девет.
function isNumber(text) {
  if (text.length === 0 || text.length > 9) return false;
  for (const c of text) {
    if (c < "0" || c > "9") return false;
  }
  return true;
}


function need(values, key) {
  if (!values.has(key)) throw new SaveError(`липсва ${key}`);
  return values.get(key);
}


function needNumber(values, key) {
  const value = need(values, key);
  if (!isNumber(value)) throw new SaveError(`грешна стойност на ${key}`);
  return Number(value);
}


function readValues(text) {
  const lines = text.split("\n");
  if (lines[lines.length - 1] === "") lines.pop();
  if (lines.length === 0 || lines[0] !== "format=" + SAVE_FORMAT) throw new SaveError("това не е запис на Арканум");
  const values = new Map();
  for (let i = 0; i < lines.length; i++) {
    const eq = lines[i].indexOf("=");
    if (eq <= 0) throw new SaveError(`ред ${i + 1} не е във вида ключ=стойност`);
    values.set(lines[i].substring(0, eq), lines[i].substring(eq + 1));
  }
  const version = need(values, "version");
  if (version !== String(SAVE_VERSION)) throw new SaveError(`версия ${version}, а играта чете версия ${SAVE_VERSION}`);
  const last = lines[lines.length - 1];
  if (!last.startsWith("checksum=")) throw new SaveError(`липсва checksum`);
  const body = lines.slice(0, lines.length - 1).join("\n") + "\n";
  const actual = checksum(body);
  const stored = last.substring(9);
  if (stored !== String(actual)) throw new SaveError(`контролната сума не съвпада (записана ${stored}, изчислена ${actual}), някой е пипал файла`);
  return values;
}

Редът е важен: заглавие (format=ARCANUM), всеки ред да е ключ=стойност, версията, сумата. Сумата се смята от всичко над последния ред и се сравнява със записаната там; need и needNumber са стражите на ключовете (липсва ли, и числото число ли е).

После героят и самото зареждане:

function readHero(values) {
  const name = need(values, "hero.name");
  const level = needNumber(values, "hero.level");
  const hp = needNumber(values, "hero.hp");
  const gold = needNumber(values, "hero.gold");
  const x = needNumber(values, "hero.x");
  const y = needNumber(values, "hero.y");
  const hero = new Hero(name, level, hp, gold, x, y);
  const bag = need(values, "hero.inventory");
  if (bag !== "-") {
    for (const part of bag.split(",")) {
      const pieces = part.split(":");
      if (pieces.length !== 2 || !isNumber(pieces[1])) throw new SaveError(`грешна стойност на hero.inventory`);
      hero.inventory.push(new Slot(pieces[0], Number(pieces[1])));
    }
  }
  return hero;
}


// Връща null, ако всичко е минало, иначе текста на проблема.
function loadGame(game, text) {
  try {
    const values = readValues(text);
    const hero = readHero(values);
    const turn = needNumber(values, "turn");
    // Всичко е прочетено и проверено: чак сега се пипа играта.
    game.hero = hero;
    game.turn = turn;
    return null;
  } catch (error) {
    if (!(error instanceof SaveError)) throw error;
    return `Записът е развален: ${error.message}. Играта продължава без него.`;
  }
}

readHero събира героя от таблицата; loadGame е кратка обвивка: чете героя и хода и чак тогава ги присвоява. SaveError се хваща и става текст; това, което тръгва, е играта без промяна. Резултатът е null при успех или съобщение за играча. Ето запис и зареждане в друга игра:

const iva = new Game(new Hero("Iva", 3, 27, 42, 5, 2), 212);
iva.hero.inventory.push(new Slot("potion_heal", 2));
iva.hero.inventory.push(new Slot("leather", 1));
const text = saveGame(iva);


const copy = new Game(new Hero("Boris", 1, 10, 7, 0, 0), 0);
const error = loadGame(copy, text);
console.log(error === null ? "ok" : error);
console.log(heroLine(copy.hero));
console.log(saveGame(copy) === text ? "Записът, написан наново, е същият." : "Записът, написан наново, е различен.");
Изход
ok
Iva: ниво 3, живот 27, злато 42
Записът, написан наново, е същият.

Записът на заредената игра е същият текст като първия: затова записът и зареждането са огледални. Борис е изчезнал, Ива е в играта.

Number("") е 0, а Number(" 7") е 7, затова isNumber проверява сам, че са само цифри (най-много девет). catch (error) в JavaScript хваща всичко, затова loadGame връща само нашите SaveError, а чуждата грешка хвърля пак: бъг в кода не бива да се маскира като „развален запис“.
По-точно, за любопитните

Каноничният loadGame прави още нещо: ако при четене падне грешка, която не е SaveError (например ръчно развален запис с вярна сума и число с неочакван вид в ред, който се чете с toInt), я превръща в „полетата не са във вида, който играта пише“. Правилото „докато чета, не пипам играта“ прави това безопасно: каквато и грешка да падне, играта е същата. Именно такъв запис срутваше първата версия на канона.

Връщането на null или текст е стил на канона: екранът пише резултата в менюто. В друг код същото би било изключение, което стига до екрана.

Виж го

Запис, сума, отказ

Ето записа и зареждането по ходове. Ива се пише ред по ред, сумата расте с всеки ред. Друга игра (Борис) зарежда записа: проверките минават през заглавието, версията и всичките редове и сумата се получава същата. После златото е вдигнато на 99999 и зареждането отказва.

// Сумата е от символите на всичко над нея; ако някой промени и една буква, тя не съвпада.
function checksum(text) {
  let sum = 0;
  for (let i = 0; i < text.length; i++) sum = (sum * 31 + text.charCodeAt(i)) % 1000000007;
  return sum;
}


function sign(body) {
  return body + "checksum=" + checksum(body) + "\n";
}


function saveGame(game) {
  const hero = game.hero;
  const lines = [];
  lines.push("format=" + SAVE_FORMAT);
  lines.push("version=" + SAVE_VERSION);
  lines.push("turn=" + game.turn);
  lines.push("hero.name=" + hero.name);
  lines.push("hero.level=" + hero.level);
  lines.push("hero.hp=" + hero.hp);
  lines.push("hero.gold=" + hero.gold);
  lines.push("hero.x=" + hero.x);
  lines.push("hero.y=" + hero.y);
  const bag = [];
  for (const slot of hero.inventory) bag.push(slot.id + ":" + slot.count);
  lines.push("hero.inventory=" + joinOrDash(bag));
  return sign(lines.join("\n") + "\n");
}


function readValues(text) {
  const lines = text.split("\n");
  if (lines[lines.length - 1] === "") lines.pop();
  if (lines.length === 0 || lines[0] !== "format=" + SAVE_FORMAT) throw new SaveError("това не е запис на Арканум");
  const values = new Map();
  for (let i = 0; i < lines.length; i++) {
    const eq = lines[i].indexOf("=");
    if (eq <= 0) throw new SaveError(`ред ${i + 1} не е във вида ключ=стойност`);
    values.set(lines[i].substring(0, eq), lines[i].substring(eq + 1));
  }
  const version = need(values, "version");
  if (version !== String(SAVE_VERSION)) throw new SaveError(`версия ${version}, а играта чете версия ${SAVE_VERSION}`);
  const last = lines[lines.length - 1];
  if (!last.startsWith("checksum=")) throw new SaveError(`липсва checksum`);
  const body = lines.slice(0, lines.length - 1).join("\n") + "\n";
  const actual = checksum(body);
  const stored = last.substring(9);
  if (stored !== String(actual)) throw new SaveError(`контролната сума не съвпада (записана ${stored}, изчислена ${actual}), някой е пипал файла`);
  return values;
}


// Връща null, ако всичко е минало, иначе текста на проблема.
function loadGame(game, text) {
  try {
    const values = readValues(text);
    const hero = readHero(values);
    const turn = needNumber(values, "turn");
    // Всичко е прочетено и проверено: чак сега се пипа играта.
    game.hero = hero;
    game.turn = turn;
    return null;
  } catch (error) {
    if (!(error instanceof SaveError)) throw error;
    return `Записът е развален: ${error.message}. Играта продължава без него.`;
  }
}
Стъпка по стъпка, с думи
  1. Играта на Ива е в паметта. За записа я пишем като текст, ред по ред „ключ=стойност“. Най-отгоре са форматът и версията: така зареждането знае дали чете запис на тази игра и на тази версия.
  2. Следват редовете на света: ход, име, ниво, живот, злато, място и торба. Торбата е един ред (предмет:брой), празната е „-“. Всеки ред е едно нещо, което играта трябва да знае, за да продължи оттам.
  3. Последният ред е контролната сума. Тя расте с всеки ред (числото вдясно): сумата се умножава по 31 и се добавя кодът на всеки знак. Всичко над нея дава 624337035; промени един знак и числото е друго.
  4. Друга игра (Борис) зарежда записа. Зареждането още не пипа играта: първо чете. Проверява заглавието (формат), всеки ред да е „ключ=стойност“ и версията.
  5. Сумата се смята наново от същите редове (лентата минава през тях). Получава се 624337035, колкото е записано: файлът е такъв, какъвто е писан.
  6. Чак сега, когато всичко е прочетено и проверено, играта на Борис получава героя от записа. Ива е заредена: 42 злато, ниво 3.
  7. Някой отваря файла и вдига златото: hero.gold=42 става hero.gold=99999. Файлът още е четим текст, всеки ред е „ключ=стойност“. Но сумата в края е написана за старите редове.
  8. Зареждането пак смята сумата. До златото числата са същите, оттам са други (в оранжево) и накрая се получава 748631855. Записаната е 624337035: не съвпадат.
  9. Отказ: „Записът е развален: контролната сума не съвпада (записана 624337035, изчислена 748631855), някой е пипал файла. Играта продължава без него.“ Играта остава каквато е: Ива с 42 злато. 99999 не стига до нея.

Кодът до сцената е checksum, sign, saveGame, readValues и loadGame от програмата. На всяка стъпка светят редовете, които работят в този момент.

Идеята

Шест развалени записа

Чете се записът на Ива, но шест пъти преди това файлът е развален по различен начин. Програмата пуска всичките в играта на Борис и печата отказа за всеки. resign в нея е „някой, който знае как се смята сумата“:

// Маха старата сума и слага нова: това е „някой, който знае как се смята сумата“.
function resign(text) {
  return sign(text.substring(0, text.lastIndexOf("checksum=")));
}


function heroLine(hero) {
  return hero.name + ": ниво " + hero.level + ", живот " + hero.hp + ", злато " + hero.gold;
}
const iva = new Game(new Hero("Iva", 3, 27, 42, 5, 2), 212);
iva.hero.inventory.push(new Slot("potion_heal", 2));
iva.hero.inventory.push(new Slot("leather", 1));
const good = saveGame(iva);


const broken = [];
// Някой е вдигнал златото на ръка: сумата е стара.
broken.push(good.replace("hero.gold=42", "hero.gold=99999"));
// Файл на друга игра.
broken.push(good.replace("format=ARCANUM", "format=SOLITAIRE"));
// Записан от по-нова версия на играта.
broken.push(good.replace("version=1", "version=2"));
// Липсва ред, сумата е пресметната наново.
broken.push(resign(good.replace("hero.gold=42\n", "")));
// Лошо число, сумата е пресметната наново.
broken.push(resign(good.replace("hero.level=3", "hero.level=three")));
// Ред без знак за равно.
broken.push(good.replace("hero.hp=27", "hero.hp 27"));


const game = new Game(new Hero("Boris", 1, 10, 7, 0, 0), 0);
for (let i = 0; i < broken.length; i++) {
  console.log((i + 1) + ": " + loadGame(game, broken[i]));
}
console.log(heroLine(game.hero));
// Целият запис влиза.
console.log(loadGame(game, good) === null ? "ok" : "no");
console.log(heroLine(game.hero));
Изход
1: Записът е развален: контролната сума не съвпада (записана 624337035, изчислена 748631855), някой е пипал файла. Играта продължава без него.
2: Записът е развален: това не е запис на Арканум. Играта продължава без него.
3: Записът е развален: версия 2, а играта чете версия 1. Играта продължава без него.
4: Записът е развален: липсва hero.gold. Играта продължава без него.
5: Записът е развален: грешна стойност на hero.level. Играта продължава без него.
6: Записът е развален: ред 6 не е във вида ключ=стойност. Играта продължава без него.
Boris: ниво 1, живот 10, злато 7
ok
Iva: ниво 3, живот 27, злато 42

Всеки отказ е на собствена проверка:

№ Какво е пипнато Коя проверка го хваща
1 златото вдигнато на ръка, сумата е стара сума: записаната и изчислената се различават
2 файл на друга игра заглавие: първият ред не е format=ARCANUM
3 запис от версия 2 версия: минава преди сумата
4 липсва ред, сумата е наново и вярна съдържание: need не намира hero.gold
5 hero.level=three, сумата е наново и вярна съдържание: needNumber не вижда число
6 ред без знак за равно форма на реда: още при разчитането

Четвъртият и петият минават покрай сумата, защото са подписани наново: затова зареждането има и втори слой. Сумата хваща повреда, а need и needNumber хващат файл, който е цял и грешен.

Накрая Борис е непокътнат (Boris: ниво 1 ...), докато не влезе здравият запис: тогава е Ива. Нито един от шестте не го е променил.

Идеята

В играта

Малкият свят е същият като в канона, само по-малък. Ето истинската контролна сума. Смятането е същото; разликата е само в типа на резултата:

function checksum(text) {
  let sum = 0;
  for (let i = 0; i < text.length; i++) sum = (sum * 31 + text.charCodeAt(i)) % 1000000007;
  return sum;
}

А ето записът на цялата игра. Освен нашите редове има seed, rng, ids и summary (редът за менюто със слотове: име, клас, ниво и място), а за всяко от трите нива редовете на картата, видяното, украсата, предметите, враговете с ефектите им и хората:

function saveGame(game) {
  const lines = [];
  const put = (key, value) => lines.push(key + '=' + value);
  const hero = game.hero;
  put('format', SAVE_FORMAT);
  put('version', SAVE_VERSION);
  put('summary', t('slot.summary', { name: hero.name, heroClass: nm(hero.heroClass()), level: hero.level, place: placeName(game) }));
  put('seed', game.seed);
  put('rng', game.rng.state);
  put('ids', game.ids.next);
  put('turn', game.turn);
  put('depth', game.depth);
  put('victory', game.victory ? 1 : 0);
  put('hero.name', hero.name);
  put('hero.class', hero.classId);
  put('hero.level', hero.level);
  put('hero.xp', hero.xp);
  put('hero.gold', hero.gold);
  put('hero.hp', hero.hp);
  put('hero.mana', hero.mana);
  put('hero.x', hero.x);
  put('hero.y', hero.y);
  const base = [];
  for (const stat of STAT_NAMES) base.push(hero.base.get(stat));
  put('hero.base', base.join(','));
  put('hero.skills', joinOrDash(hero.skills));
  put('hero.cooldowns', cooldownsText(hero));
  put('hero.effects', effectsText(hero));
  const equipment = [];
  for (const slot of hero.equipment.keys()) equipment.push(hero.equipment.get(slot) === '' ? '-' : hero.equipment.get(slot));
  put('hero.equipment', equipment.join(','));
  const inventory = [];
  for (const slot of hero.inventory.slots) inventory.push(slot.id + ':' + slot.count);
  put('hero.inventory', joinOrDash(inventory));
  const stats = game.stats;
  put('stats', [stats.turns, stats.kills, stats.blood, stats.dealt, stats.taken, stats.potions].join(','));
  put('flags', joinOrDash(game.flags));
  for (const quest of game.quests) put('quest.' + quest.id, quest.state + ':' + quest.stage);
  for (const level of game.levels) {
    const prefix = 'level.' + level.depth + '.';
    for (let y = 0; y < level.height; y++) {
      let seen = '';
      let decor = '';
      for (let x = 0; x < level.width; x++) {
        seen += level.seen[y][x] ? '1' : '0';
        decor += level.decor[y][x] === ' ' ? '_' : level.decor[y][x];
      }
      put(prefix + 'tiles.' + y, level.tiles[y].join(''));
      put(prefix + 'seen.' + y, seen);
      put(prefix + 'decor.' + y, decor);
    }
    const items = [];
    for (const item of level.items) items.push(item.x + ':' + item.y + ':' + item.id + ':' + item.count);
    put(prefix + 'items', joinOrDash(items));
    put(prefix + 'enemies', level.enemies.length);
    for (let i = 0; i < level.enemies.length; i++) {
      const enemy = level.enemies[i];
      put(prefix + 'enemy.' + i, [enemy.kind.id, enemy.x, enemy.y, enemy.hp, enemy.state, enemy.calm, enemy.lostTurns, enemy.phase].join(','));
      put(prefix + 'enemy.' + i + '.effects', effectsText(enemy));
      put(prefix + 'enemy.' + i + '.cooldowns', cooldownsText(enemy));
    }
    const npcs = [];
    for (const npc of level.npcs) npcs.push(npc.id + ':' + npc.x + ':' + npc.y);
    put(prefix + 'npcs', joinOrDash(npcs));
  }
  const body = lines.join('\n') + '\n';
  return body + 'checksum=' + checksum(body) + '\n';
}

Четенето в канона е клас SaveReader: конструкторът прави същите проверки като нашия readValues, а text, int, ints и list са стражите. Ето го:

class SaveReader {
  constructor(text) {
    this.values = new Map();
    const lines = text.split('\n');
    while (lines.length > 0 && lines[lines.length - 1].length === 0) lines.pop();
    if (lines.length === 0 || lines[0] !== 'format=' + SAVE_FORMAT) throw new SaveError(t('load.badHeader'));
    for (let i = 0; i < lines.length; i++) {
      const eq = lines[i].indexOf('=');
      if (eq <= 0) throw new SaveError(t('load.badLine', { line: i + 1 }));
      this.values.set(lines[i].substring(0, eq), lines[i].substring(eq + 1));
    }
    const version = this.text('version');
    if (version !== String(SAVE_VERSION)) throw new SaveError(t('load.badVersion', { found: version, expected: SAVE_VERSION }));
    const last = lines[lines.length - 1];
    if (!last.startsWith('checksum=')) throw new SaveError(t('load.missing', { key: 'checksum' }));
    const body = lines.slice(0, lines.length - 1).join('\n') + '\n';
    const actual = checksum(body);
    if (parseIntStrict(last.substring(9)) !== actual) {
      throw new SaveError(t('load.badChecksum', { expected: last.substring(9), actual: actual }));
    }
  }


  text(key) {
    if (!this.values.has(key)) throw new SaveError(t('load.missing', { key: key }));
    return this.values.get(key);
  }


  int(key) {
    const value = parseIntStrict(this.text(key));
    if (value === null) throw new SaveError(t('load.badValue', { key: key }));
    return value;
  }


  ints(key, count) {
    const parts = this.text(key).split(',');
    if (parts.length !== count) throw new SaveError(t('load.badValue', { key: key }));
    const result = [];
    for (const part of parts) {
      const value = parseIntStrict(part);
      if (value === null) throw new SaveError(t('load.badValue', { key: key }));
      result.push(value);
    }
    return result;
  }


  list(key) {
    return splitList(this.text(key));
  }
}

И обвивката, която пази играта. Присвояването е след коментара „Всичко е прочетено“, а catch превръща всяка грешка в текст:

// Връща null при успех или текста на грешката.
function loadGame(game, text) {
  if (text === null) return t('load.empty');
  try {
    const reader = new SaveReader(text);
    const ids = new IdSource(1);
    const hero = readHero(reader, ids);
    const levels = [];
    for (const def of MAP_DEFS) levels.push(readLevel(reader, def, ids));
    const quests = createQuests();
    for (const quest of quests) {
      const pieces = reader.text('quest.' + quest.id).split(':');
      if (pieces.length !== 2) throw new SaveError(t('load.badValue', { key: 'quest.' + quest.id }));
      quest.state = pieces[0];
      quest.stage = toInt(pieces[1]);
    }
    const stats = reader.ints('stats', 6);
    const depth = reader.int('depth');
    if (depth < 0 || depth > levels.length) throw new SaveError(t('load.badValue', { key: 'depth' }));
    // Всичко е прочетено: чак сега се пипа играта.
    game.hero = hero;
    game.levels = levels;
    game.useQuests(quests);
    game.flags = reader.list('flags');
    game.stats = { turns: stats[0], kills: stats[1], blood: stats[2], dealt: stats[3], taken: stats[4], potions: stats[5] };
    game.depth = depth;
    game.turn = reader.int('turn');
    game.victory = reader.int('victory') === 1;
    game.rng.state = reader.int('rng') >>> 0;
    game.ids = new IdSource(Math.max(reader.int('ids'), ids.next));
    game.messages = [];
    if (depth > 0) computeFov(game.level(), hero.x, hero.y);
    return null;
  } catch (error) {
    // До „чак сега се пипа играта“ кодът само чете: каквато и грешка да падне, тя идва от данните.
    const reason = error instanceof SaveError ? error.message : t('load.badData');
    return t('load.broken', { reason: reason });
  }
}

Какво още има в играта около този код:

  • Слотове. Менюто пише в слот 1, 2 или 3 чрез io.save(слот, текст) и чете чрез io.load(слот). В Node това са файлове в папка saves, в браузъра запис в localStorage. Самият запис не знае къде отива.
  • Развален слот за проверка. С --memory-saves записите са в паметта и main слага в слот 3 записа от tamperedSave(), на езика на играта: запис с hero.gold=99999 и сума, която не е на този текст. Така в записаното минаване на играта се вижда отказът: менюто пише „Записът е развален“ и играта продължава.
  • Резюме на слота. slotSummary чете само реда summary=, без да зарежда света: така менюто показва „Iva, варварин, ур.4, Сивия брод“ за всеки слот.
  • След зареждане. loadGame изчиства съобщенията и смята видимото наново с computeFov, а enterWorld казва „Заредено от слот 1“ и подменя стека с екрана на града или на картата (виж урока за стека на екраните).

Пробвай

Намери грешката

Колега реши, че е по-просто да слага стойностите направо в играта, докато ги чете. Подава се запис с вярна сума, но с hero.level=three:

const iva = new Game(new Hero("Iva", 3, 27, 42, 5, 2), 212);
iva.hero.inventory.push(new Slot("potion_heal", 2));
iva.hero.inventory.push(new Slot("leather", 1));
const game = new Game(new Hero("Boris", 1, 10, 7, 0, 0), 0);


const text = resign(saveGame(iva).replace("hero.level=3", "hero.level=three"));
console.log(loadGame(game, text));
console.log(heroLine(game.hero));
Изход
Записът е развален: грешна стойност на hero.level. Играта продължава без него.
Iva: ниво 1, живот 10, злато 7

Зареждането отказва, както трябва, но играта не е същата: името е Ива, а нивото, животът и златото са на Борис. Кой ред е първият, който пипа играта, преди записът да е прочетен докрай?

Избери реда с грешката.

По-точно

По-точно: сума, версии и какво още може да се обърка

Сумата не е подпис. Нашата е смесване на знаци с модул; има готови и по-силни: CRC32 хваща повреда от диск и мрежа по-надеждно, а SHA-256 е почти невъзможно да се подмени без да се усети. Но дори те не пазят от човек, който знае алгоритъма и пише нова вярна сума: resign в програмата прави точно това. Само подпис с таен ключ (HMAC) би го хванал, а в игра за един играч на неговия компютър няма таен ключ и няма смисъл от такава защита. Сумата тук е за повреда и непохватно пипане. Който иска да мами в игра за един, ще го направи, и това е негова работа.

Версии и миграции. Всяка промяна във формата е нова версия. Три пътя: да отказваш (нашето зареждане: „версия 2, а играта чете версия 1“), да четеш и старите версии с вграден превод (упражнението по-долу) или да ги четеш всички завинаги. Последното расте: след години в зареждането има код за дузина версии. Затова често се прави верига „миграции“: версия 1 → 2 → 3, всяка стъпка малка и с тест.

Запис по средата. Токът спира, докато файлът се пише: на диска остава половин файл. Контролната сума го хваща (последният ред липсва, „липсва checksum“), но и записът на играча е изгубен. По-добре е да пишеш във временен файл и да го преименуваш върху стария едва когато е записан докрай; преименуването е цяла операция. Нашият io.save пише направо, защото урокът не е за файлови системи.

Защо не JSON. JSON би свършил работа и ще го видиш в други уроци. Тук текстът ключ=стойност е нарочно прост: изходът трябва да е еднакъв на четири езика без библиотеки, а целият формат се чете на един екран. Цената е, че вложените неща (торба, враг с ефекти) се слепват на ръка с : и ,.

Двоичен формат. По-малък и по-бърз, но не се чете и не се сравнява с очи. За текстова игра с няколко килобайта записи е излишен.

Упражнение

Версия 2: мана

Реши задачата в редактора си. Тръгни от програмата за зареждането.

Мана и две версии. Героят получава мана (mana, по подразбиране 10). Версия 2 на формата добавя ред hero.mana веднага след hero.hp. Играта вече пише версия 2, но още чете и записи от версия 1: те нямат мана и героят я получава по подразбиране. Версия 3 (и нагоре) се отказва със същото съобщение като досега, а readValues приема версия между 1 и най-новата. Реши така, че loadGame да върне null и за двата вида записа.

Ето записа от версия 1 (какъвто го пише програмата от урока), помощната функция и тялото:

// Запис, какъвто го пише версия 1 на играта.
const V1_SAVE = [
  "format=ARCANUM",
  "version=1",
  "turn=212",
  "hero.name=Iva",
  "hero.level=3",
  "hero.hp=27",
  "hero.gold=42",
  "hero.x=5",
  "hero.y=2",
  "hero.inventory=potion_heal:2,leather:1",
  "checksum=624337035",
].join("\n") + "\n";


function check(game, number, text) {
  const error = loadGame(game, text);
  console.log(number + ": " + (error === null ? "ok" : error));
  console.log(heroLine(game.hero));
}


const source = new Game(new Hero("Iva", 3, 27, 42, 5, 2), 212);
source.hero.inventory.push(new Slot("potion_heal", 2));
source.hero.inventory.push(new Slot("leather", 1));
source.hero.mana = 8;
const v2 = saveGame(source);


const game = new Game(new Hero("Boris", 1, 10, 7, 0, 0), 0);
check(game, 1, V1_SAVE);
check(game, 2, v2);
check(game, 3, v2.replace("version=2", "version=3"));

Изходът е:

Изход
1: ok
Iva: ниво 3, живот 27, злато 42, мана 10
2: ok
Iva: ниво 3, живот 27, злато 42, мана 8
3: Записът е развален: версия 3, а играта чете версия 2. Играта продължава без него.
Iva: ниво 3, живот 27, злато 42, мана 8

Още задачи

  • Автоматичен запис. Пиши в отделен слот auto на всеки 100 хода. Как менюто разбира, че слотът е автоматичен?
  • Откъснат файл. Махни последния ред от запис (без сумата). Какво казва зареждането? Промени io.save да пише във временен файл и да го преименува.
  • Резюме на слота. Добави ред summary= с името и нивото и функция, която го чете, без да зарежда света, като slotSummary в канона.
  • Два пъти един ключ. Сега последният hero.gold= печели тихо, защото таблицата замества. Накарай readValues да отказва записи с повтарящ се ключ.

Тест

Провери се

1. Записът е от версия 2 и сумата му не съвпада, но го зареждаш в игра, която чете версия 1. Коя грешка ще види играчът и защо?
2. Сумата на „ab“ е 3105, а на „ba“ е 3135. Защо тя не е просто сбор от кодовете на знаците (195 и за двата низа)?
3. Някой, който знае как се смята сумата, вдига златото на 99999 и записва в края сумата на новия текст. Какво става при зареждане?
4. Зареждането чете всичко в локални променливи и чак после ги слага в играта. Защо?
5. Канонът записва и състоянието на генератора на случайни числа (rng). Защо?

Създаден от Иво Гергов като част от кампанията на Evo Tech за достъпно обучение по програмиране ·