Settings, config and saves: the source

since 0.7.0 Widgets and the rest
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: config (line 27), save (line 44), use (line 111).
1/// What a player has changed about how the game behaves for them, and where
2/// a run in progress is kept between launches.
3///
4/// **`flutter3d_game`'s real `GameConfig`, `SaveFile` and `SettingsPanel` are
5/// not a dependency of this app.** `GameConfig` is two maps of numbers with
6/// no file and no platform behind it; this page reimplements exactly that
7/// shape. `SaveFile` is thinner still — underneath its own few lines it is
8/// entirely the real `Storage` and `Snapshot` this app already depends on
9/// through `flutter3d_app` and `flutter3d_sim`, so this page's version calls
10/// those directly rather than reimplementing anything of substance.
11/// `SettingsPanel` itself is a Flutter widget over a `Bindings` and a
12/// gamepad's dead zone, both of which live in packages this app does not
13/// have; it is described in the guide rather than built here.
14///
15/// Quoted by `game_settings.md` and shown whole in the Source tab.
16library;

18import 'dart:convert';

20import 'package:flutter/widgets.dart';
21import 'package:flutter3d/flutter3d.dart';
22import 'package:flutter3d_app/flutter3d_app.dart';
23import 'package:flutter3d_showcase/src/demo/demo.dart';
24import 'package:flutter3d_sim/flutter3d_sim.dart';
25import 'package:vector_math/vector_math.dart';

27/// Everything a player has changed, as two maps of numbers: no file, no
28/// path, no platform. Where the bytes go is the application's business.
29final class _GameConfig {
_GameConfig({Map<String, double>? volumes, Map<String, double>? settings})
  : volumes = <String, double>{...?volumes},
    settings = <String, double>{...?settings};

final Map<String, double> volumes;
final Map<String, double> settings;

double volumeOf(String bus) => volumes[bus] ?? 1.0;
void setVolume(String bus, double volume) =>
    volumes[bus] = volume.clamp(0.0, 1.0);
double settingOf(String name, double fallback) => settings[name] ?? fallback;
void setSetting(String name, double value) => settings[name] = value;
42}

44/// Where a run in progress is kept. Everything below the field names is the
45/// real `Storage` and `Snapshot` this app already depends on.
46final class _SaveFile {
_SaveFile({required String appName}) : _storage = defaultStorage(appName);

final Storage _storage;
static const String _name = 'save.json';

({String level, Snapshot run})? read() {
  final text = _storage.read(_name);
  if (text == null) return null;
  final json = jsonDecode(text) as Map<String, Object?>;
  return (
    level: json['level']! as String,
    run: Snapshot.fromJson(json['run']! as Map<String, Object?>),
  );
}

bool write(String level, Snapshot run) => _storage.write(
  _name,
  jsonEncode(<String, Object?>{'level': level, 'run': run.toJson()}),
);

void clear() => _storage.remove(_name);
68}

70final class GameSettingsDemo extends ShowcaseDemo {
late final String _report;
late final double _musicVolume;
late final double _sfxVolume;
late final String? _resumedLevel;
late final double? _resumedX;
late final bool _clearedSaveIsGone;

@override
Scene build(DemoContext context) {
  final (
    String report,
    double musicVolume,
    double sfxVolume,
    String? resumedLevel,
    double? resumedX,
    bool clearedSaveIsGone,
  ) = _run();
  _report = report;
  _musicVolume = musicVolume;
  _sfxVolume = sfxVolume;
  _resumedLevel = resumedLevel;
  _resumedX = resumedX;
  _clearedSaveIsGone = clearedSaveIsGone;
  final material = Material(
    name: 'panel',
    baseColor: Vector4(0.5, 0.7, 0.5, 1.0),
  );
  final node = MeshNode(
    DeviceMesh.upload(context.device, SphereShape(segments: 16).build()),
    material,
  );
  return Scene()
    ..add(node)
    ..add(
      LightNode(name: 'sun', intensity: 3.0)
        ..setLocalForward(Vector3(-0.4, -1.0, -0.3)),
    );
}

static (String, double, double, String?, double?, bool) _run() {
  final config = _GameConfig()
    ..setVolume('music', 0.6)
    ..setSetting('a11y.cameraMotion', 0.0);
  final musicVolume = config.volumeOf('music');
  final sfxVolume = config.volumeOf('sfx');
  final cameraMotion = config.settingOf('a11y.cameraMotion', 1.0);

  final save = _SaveFile(appName: 'flutter3d-showcase-demo');
  final snapshot = Snapshot(<String, Object?>{'x': 4.5});
  save.write('levels/one.json', snapshot);
  final resumed = save.read();
  save.clear();
  final afterClear = save.read();

  final resumedX = (resumed?.run.data['x'] as num?)?.toDouble();
  final report =
      'music volume: $musicVolume, sfx (never set): $sfxVolume\n'
      'camera motion setting: $cameraMotion\n'
      'resumed at level ${resumed?.level}, x=$resumedX\n'
      'after clearing the save: $afterClear';
  return (
    report,
    musicVolume,
    sfxVolume,
    resumed?.level,
    resumedX,
    afterClear == null,
  );
}

@override
Widget? customBody(BuildContext buildContext, DemoContext context) =>
    Container(
      color: const Color(0xFF14161A),
      padding: const EdgeInsets.all(24),
      alignment: Alignment.topLeft,
      child: DefaultTextStyle(
        style: const TextStyle(color: Color(0xFFE8E8EC), fontSize: 16),
        child: Text(_report),
      ),
    );

@override
void verify(Scene scene, FrameResult frame) {
  if (frame.drawCalls < 1) {
    throw StateError('the panel marker was not drawn');
  }
  // Compared as numbers, not read back out of `_report`: `sfxVolume`'s
  // default is a whole-number double, and a web backend prints one of
  // those without its trailing `.0` — a compiled `1` failing a substring
  // match against `'sfx (never set): 1.0'` would be this check catching
  // its own string, not the config.
  if (_musicVolume != 0.6 || _sfxVolume != 1.0) {
    throw StateError('a bus nobody set should default to full volume');
  }
  if (_resumedLevel != 'levels/one.json' || _resumedX != 4.5) {
    throw StateError(
      'a written save should read back with its own level '
      'and its own state',
    );
  }
  if (!_clearedSaveIsGone) {
    throw StateError('a cleared save should read back as nothing');
  }
}
176}