phaneron/Kelsidavis-WoWee
1
0
Fork 0
mirror of https://github.com/Kelsidavis/WoWee.git synced 2026-05-11 11:33:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

feat(pipeline): WCAM camera presets catalog (144th open format)

Browse source 
Novel format covering what vanilla WoW handled with hard-coded
camera profiles in the client's CameraMgr (the standard third-
person camera, the flight-path camera, vehicle cameras and
cinematic cameras were all bespoke C++ classes with no data-
driven extension point). Each WCAM entry binds one camera
preset to its FOV, distance, pitch/yaw offsets, shoulder offset,
focus-bone tracking target (M2 bone index, 0xFFFF = follow root),
motion damping curve (0=instant follow / 255=maximum lag), and
intended purpose (Cinematic / Combat / Mounted / Vehicle /
Cutscene / PhotoMode).

Three presets covering common camera scenarios:
  --gen-cam-combat     3 Combat variants (default 75deg / wide
                       ranged 90deg / tight melee 60deg
                       shoulder-cam tracking chest bone) with
                       low motion damping (8-15) for responsive
                       tracking
  --gen-cam-mounted    2 Mounted variants (ground 80deg pulled-
                       back / flying 85deg high-pitch wing-frame)
                       with medium-high damping (60-90) for
                       smooth turning
  --gen-cam-cinematic  3 Cinematic angles (over-shoulder
                       dialogue 50deg telephoto / wide
                       establishing 100deg / portrait 35deg
                       3/4-face composition with yaw offset and
                       head-bone tracking) with high damping
                       (180-220) for film-quality motion

Validator catches: id+name required, purposeKind 0..5, no
duplicate presetIds, FOV in (0,180) (zero/negative makes no
sense, >=180 inverts the view frustum), distanceFromTarget >= 0
(negative places camera in front of target). CRITICAL: pitch
within (-89, +89) — beyond gimbal-locks the camera. Warns on
FOV outside 30..120 player-comfort range (motion-sickness risk
or extreme telephoto compression), distanceFromTarget < 0.5m
(clips into model), and yawOffsetDegrees beyond ±180° (wraps to
smaller equivalent angle — simplify).

Format count 143 -> 144. CLI flag count 1490 -> 1497.
This commit is contained in:
Kelsi 2026-05-10 05:54:48 -07:00
parent 7fbf35e98c
commit ab69171ad9
10 changed files with 722 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

301
tools/editor/cli_camera_presets_catalog.cpp Normal file
View file

@ -0,0 +1,301 @@
#include "cli_camera_presets_catalog.hpp"
#include "cli_arg_parse.hpp"
#include "cli_box_emitter.hpp"
#include "pipeline/wowee_camera_presets.hpp"
#include <nlohmann/json.hpp>
#include <cmath>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <fstream>
#include <set>
#include <string>
#include <vector>
namespace wowee {
namespace editor {
namespace cli {
namespace {
std::string stripWcamExt(std::string base) {
stripExt(base, ".wcam");
return base;
}
const char* purposeKindName(uint8_t k) {
using C = wowee::pipeline::WoweeCameraPresets;
switch (k) {
case C::Cinematic: return "cinematic";
case C::Combat: return "combat";
case C::Mounted: return "mounted";
case C::Vehicle: return "vehicle";
case C::Cutscene: return "cutscene";
case C::PhotoMode: return "photomode";
default: return "?";
}
}
bool saveOrError(const wowee::pipeline::WoweeCameraPresets& c,
const std::string& base, const char* cmd) {
if (!wowee::pipeline::WoweeCameraPresetsLoader::save(c, base)) {
std::fprintf(stderr, "%s: failed to save %s.wcam\n",
cmd, base.c_str());
return false;
}
return true;
}
void printGenSummary(const wowee::pipeline::WoweeCameraPresets& c,
const std::string& base) {
std::printf("Wrote %s.wcam\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" presets : %zu\n", c.entries.size());
}
int handleGenCombat(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "CombatCameraPresets";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWcamExt(base);
auto c = wowee::pipeline::WoweeCameraPresetsLoader::
makeCombatPresets(name);
if (!saveOrError(c, base, "gen-cam-combat")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenMounted(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "MountedCameraPresets";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWcamExt(base);
auto c = wowee::pipeline::WoweeCameraPresetsLoader::
makeMountedPresets(name);
if (!saveOrError(c, base, "gen-cam-mounted")) return 1;
printGenSummary(c, base);
return 0;
}
int handleGenCinematic(int& i, int argc, char** argv) {
std::string base = argv[++i];
std::string name = "CinematicCameraPresets";
if (parseOptArg(i, argc, argv)) name = argv[++i];
base = stripWcamExt(base);
auto c = wowee::pipeline::WoweeCameraPresetsLoader::
makeCinematicPresets(name);
if (!saveOrError(c, base, "gen-cam-cinematic")) return 1;
printGenSummary(c, base);
return 0;
}
int handleInfo(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = consumeJsonFlag(i, argc, argv);
base = stripWcamExt(base);
if (!wowee::pipeline::WoweeCameraPresetsLoader::exists(base)) {
std::fprintf(stderr, "WCAM not found: %s.wcam\n",
base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeCameraPresetsLoader::load(base);
if (jsonOut) {
nlohmann::json j;
j["wcam"] = base + ".wcam";
j["name"] = c.name;
j["count"] = c.entries.size();
nlohmann::json arr = nlohmann::json::array();
for (const auto& e : c.entries) {
arr.push_back({
{"presetId", e.presetId},
{"name", e.name},
{"purposeKind", e.purposeKind},
{"purposeKindName",
purposeKindName(e.purposeKind)},
{"motionDamping", e.motionDamping},
{"fovDegrees", e.fovDegrees},
{"distanceFromTarget",
e.distanceFromTarget},
{"pitchDegrees", e.pitchDegrees},
{"yawOffsetDegrees", e.yawOffsetDegrees},
{"shoulderOffsetMeters",
e.shoulderOffsetMeters},
{"focusBoneId", e.focusBoneId},
});
}
j["entries"] = arr;
std::printf("%s\n", j.dump(2).c_str());
return 0;
}
std::printf("WCAM: %s.wcam\n", base.c_str());
std::printf(" catalog : %s\n", c.name.c_str());
std::printf(" presets : %zu\n", c.entries.size());
if (c.entries.empty()) return 0;
std::printf(" id purpose damp FOV dist pitch yaw shoulder bone name\n");
for (const auto& e : c.entries) {
std::printf(" %4u %-10s %3u %5.1f %6.2f %+6.1f %+5.1f %+8.2f %4u %s\n",
e.presetId,
purposeKindName(e.purposeKind),
e.motionDamping,
e.fovDegrees, e.distanceFromTarget,
e.pitchDegrees, e.yawOffsetDegrees,
e.shoulderOffsetMeters,
e.focusBoneId, e.name.c_str());
}
return 0;
}
int handleValidate(int& i, int argc, char** argv) {
std::string base = argv[++i];
bool jsonOut = consumeJsonFlag(i, argc, argv);
base = stripWcamExt(base);
if (!wowee::pipeline::WoweeCameraPresetsLoader::exists(base)) {
std::fprintf(stderr,
"validate-wcam: WCAM not found: %s.wcam\n",
base.c_str());
return 1;
}
auto c = wowee::pipeline::WoweeCameraPresetsLoader::load(base);
std::vector<std::string> errors;
std::vector<std::string> warnings;
if (c.entries.empty()) {
warnings.push_back("catalog has zero entries");
}
std::set<uint32_t> idsSeen;
for (size_t k = 0; k < c.entries.size(); ++k) {
const auto& e = c.entries[k];
std::string ctx = "entry " + std::to_string(k) +
" (id=" + std::to_string(e.presetId);
if (!e.name.empty()) ctx += " " + e.name;
ctx += ")";
if (e.presetId == 0)
errors.push_back(ctx + ": presetId is 0");
if (e.name.empty())
errors.push_back(ctx + ": name is empty");
if (e.purposeKind > 5) {
errors.push_back(ctx + ": purposeKind " +
std::to_string(e.purposeKind) +
" out of range (0..5)");
}
// FOV must be in (0..180). Negative or zero
// FOV makes no sense; >= 180 inverts the view
// frustum.
if (e.fovDegrees <= 0.f || e.fovDegrees >= 180.f) {
errors.push_back(ctx + ": fovDegrees=" +
std::to_string(e.fovDegrees) +
" out of range (must be in (0, 180))");
}
// FOV outside human-comfort range warns. <30
// = extreme telephoto; >120 = fish-eye that
// disorients players.
if (e.fovDegrees > 0.f &&
(e.fovDegrees < 30.f || e.fovDegrees > 120.f)) {
warnings.push_back(ctx + ": fovDegrees=" +
std::to_string(e.fovDegrees) +
" outside 30..120 player-comfort range "
"— may cause motion sickness or "
"extreme telephoto compression");
}
// Negative distance places camera in front of
// target — almost certainly a typo.
if (e.distanceFromTarget < 0.f) {
errors.push_back(ctx +
": distanceFromTarget=" +
std::to_string(e.distanceFromTarget) +
" is negative — camera would render in "
"front of target");
}
// Very small distance (< 0.5m) clips into the
// model — warn, since some shots want this
// (extreme close-up portraits).
if (e.distanceFromTarget > 0.f &&
e.distanceFromTarget < 0.5f) {
warnings.push_back(ctx +
": distanceFromTarget=" +
std::to_string(e.distanceFromTarget) +
" under 0.5m — likely clips into the "
"model; verify intentional");
}
// Pitch outside ±89° gimbal-locks the camera.
if (e.pitchDegrees < -89.f ||
e.pitchDegrees > 89.f) {
errors.push_back(ctx + ": pitchDegrees=" +
std::to_string(e.pitchDegrees) +
" gimbal-locks the camera (must be "
"within (-89, +89))");
}
// Yaw beyond ±180° is degenerate (wraps).
if (std::fabs(e.yawOffsetDegrees) > 180.f) {
warnings.push_back(ctx +
": yawOffsetDegrees=" +
std::to_string(e.yawOffsetDegrees) +
" beyond ±180° — wraps to a smaller "
"equivalent angle, simplify");
}
if (!idsSeen.insert(e.presetId).second) {
errors.push_back(ctx + ": duplicate presetId");
}
}
bool ok = errors.empty();
if (jsonOut) {
nlohmann::json j;
j["wcam"] = base + ".wcam";
j["ok"] = ok;
j["errors"] = errors;
j["warnings"] = warnings;
std::printf("%s\n", j.dump(2).c_str());
return ok ? 0 : 1;
}
std::printf("validate-wcam: %s.wcam\n", base.c_str());
if (ok && warnings.empty()) {
std::printf(" OK — %zu presets, all presetIds "
"unique, purposeKind 0..5, FOV in "
"(0,180), distanceFromTarget >= 0, "
"pitch within (-89, +89)\n",
c.entries.size());
return 0;
}
if (!warnings.empty()) {
std::printf(" warnings (%zu):\n", warnings.size());
for (const auto& w : warnings)
std::printf(" - %s\n", w.c_str());
}
if (!errors.empty()) {
std::printf(" ERRORS (%zu):\n", errors.size());
for (const auto& e : errors)
std::printf(" - %s\n", e.c_str());
}
return ok ? 0 : 1;
}
} // namespace
bool handleCameraPresetsCatalog(int& i, int argc, char** argv,
int& outRc) {
if (std::strcmp(argv[i], "--gen-cam-combat") == 0 &&
i + 1 < argc) {
outRc = handleGenCombat(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-cam-mounted") == 0 &&
i + 1 < argc) {
outRc = handleGenMounted(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--gen-cam-cinematic") == 0 &&
i + 1 < argc) {
outRc = handleGenCinematic(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--info-wcam") == 0 && i + 1 < argc) {
outRc = handleInfo(i, argc, argv); return true;
}
if (std::strcmp(argv[i], "--validate-wcam") == 0 &&
i + 1 < argc) {
outRc = handleValidate(i, argc, argv); return true;
}
return false;
}
} // namespace cli
} // namespace editor
} // namespace wowee