project_plan.h

Go to the documentation of this file.

#ifndef YAZE_CORE_PROJECT_PLAN_H_
#define YAZE_CORE_PROJECT_PLAN_H_
 
#include <string>
#include <string_view>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "nlohmann/json.hpp"
 
namespace yaze::core {
 
// A project plan: goals, milestones, the intended play route, open design
// decisions and reference documents for a hack. Stored as a JSON sidecar
// (schema "yaze.plan/1") named by the `.yaze` file's [planning] section; see
// docs/public/usage/planning.md. Game-independent: nothing here reads a ROM.
//
// Every object keeps the keys this build does not model in `extra`, and the
// top level keeps unknown sections (for example "overworld" or "concepts"), so
// a plan written by a newer build or another tool survives a save.
 
using PlanJson = nlohmann::ordered_json;
 
inline constexpr std::string_view kProjectPlanSchema = "yaze.plan/1";
 
// A link from plan data to something the editor can show. Written as
// "<kind>:<id>", for example "room:0x0C", "map:0x4B", "area:D1", "step:D4",
// "item:flippers", "decision:power-approach", "marker:abyss:m3".
struct PlanTarget {
  std::string kind;
  std::string id;
 
  static PlanTarget Parse(std::string_view text);
  // Room or overworld map number for "room:" / "map:" targets, else -1.
  int NumericId() const;
};
 
struct PlanGoal {
  std::string title;
  std::string detail;
  std::string due;  // YYYY-MM-DD, optional
  PlanJson extra = PlanJson::object();
};
 
struct PlanMilestone {
  std::string id;
  std::string title;
  std::string start;   // YYYY-MM-DD, optional
  std::string end;     // YYYY-MM-DD, optional
  std::string status;  // planned | active | done
  std::string detail;
  PlanJson extra = PlanJson::object();
};
 
struct PlanRouteStep {
  std::string id;
  std::string code;  // short label such as "D4", optional
  std::string title;
  std::string note;
  std::string group;  // chapter or act heading, optional
  std::string kind;   // story | errand | dungeon | shrine | optional | boss
  std::vector<std::string> targets;
  PlanJson extra = PlanJson::object();
};
 
struct PlanNeed {
  std::string step;
  std::string what;
  PlanJson extra = PlanJson::object();
};
 
struct PlanRouteItem {
  std::string id;
  std::string name;
  std::string step;      // route step where the player gets it
  std::string category;  // gear | mask | song | quest | ...
  bool required = false;
  std::string status;  // implemented | prototype | decided | proposed | open
  std::string where;
  std::string note;
  std::vector<PlanNeed> needs;  // later steps that require it
  PlanJson extra = PlanJson::object();
};
 
struct PlanDecision {
  std::string id;
  std::string title;
  std::string status;  // open | decided | dropped
  int priority = 0;    // 1 = most urgent; 0 = unranked
  std::string recommendation;
  std::string answer;
  std::vector<std::string> targets;
  std::vector<std::string> refs;  // file paths or URLs
  PlanJson extra = PlanJson::object();
};
 
struct PlanReference {
  std::string label;
  std::string path;  // file path or URL
  std::string author;
  std::string date;
  PlanJson extra = PlanJson::object();
};
 
class ProjectPlan {
 public:
  static ProjectPlan CreateEmpty(std::string title);
  static absl::StatusOr<ProjectPlan> Parse(std::string_view text);
  static absl::StatusOr<ProjectPlan> LoadFromFile(const std::string& path);
 
  std::string Serialize() const;
  // Writes a sibling temporary file, then renames it over `path`.
  absl::Status SaveToFile(const std::string& path) const;
 
  // Index into route_steps, or -1.
  int FindStep(std::string_view id) const;
  std::vector<const PlanRouteItem*> ItemsAtStep(std::string_view step) const;
  // Decisions with status "open", most urgent first (unranked last).
  std::vector<const PlanDecision*> OpenDecisions() const;
  // The milestone marked "active", else the first one whose dates contain
  // `today` (YYYY-MM-DD), else nullptr.
  const PlanMilestone* CurrentMilestone(std::string_view today) const;
 
  std::string title;
  std::string about;
  PlanGoal goal;
  std::vector<PlanMilestone> milestones;
  std::vector<PlanRouteStep> route_steps;
  std::vector<PlanRouteItem> route_items;
  PlanJson route_extra = PlanJson::object();
  std::vector<PlanDecision> decisions;
  std::vector<PlanReference> references;
  PlanJson extra = PlanJson::object();
};
 
}  // namespace yaze::core
 
#endif  // YAZE_CORE_PROJECT_PLAN_H_