Central, modular repository for KytyPS5 patches, cheats, and game configuration presets.
kytyps5-modules/
├── patches/json/ # Game patches (memory byte patches, timing/FPS unlocks, resolution mods)
├── cheats/json/ # Game cheats (trainers, infinite health/items)
├── configs/json/ # Optimized emulator settings presets per game
├── scripts/ # Automation scripts for index generation, validation, and submission
├── index.json # Formatted global catalog
└── index.min.json # Minified global catalog for fast CDN distribution
All files strictly follow this standard naming convention:
\A(?<id>[A-Z]{4}\d{5})_(?<version>\d{2}_\d{3}_\d{3})_(?<game_name>[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*)_(?<index>\d+)\.json\z-
Title ID: Bare uppercase PS5 game Title ID (e.g.
PPSA01325). -
Version: Game version in the filename uses underscores (e.g.
01.905.000$\to$ 01_905_000). -
Game Name: Alphanumeric title with words separated by single underscores (e.g.
Astros_Playroom). -
Sequential Index: Sequential counter (
_1,_2,_3...) to handle multiple patches or cheats for the same PPSA and version without filename collisions.
patches/json/PPSA01325_01_905_000_Astros_Playroom_1.jsonpatches/json/PPSA01325_01_905_000_Astros_Playroom_2.jsonpatches/json/PPSA28997_01_008_001_God_of_War_Sons_of_Sparta_1.json
All contributions are submitted via GitHub Issue Forms:
- Navigate to Issues
$\to$ New Issue. - Select Patch Submission, Cheat Submission, or Config Submission.
- Fill in the Title ID, Game Version (e.g.
01.905.000), Game Name, and Title. - Drag and drop your
.jsonfile into the attachment field (or paste the JSON directly). - Submit the issue.
The automated submission workflow will:
- Parse and validate the form data and attached JSON.
- Assign the next available sequential filename.
- Open a Pull Request on branch
submission/<type>-<ppsa>-<version>-i<issue_number>.
flowchart TD
User["Community Member"] -->|Submits Issue Form| Issue["GitHub Issue"]
Issue -->|triggers| Wf["GitHub Action: submission.yml"]
Wf --> Parse["Parse form fields + Download attached JSON"]
Parse --> Validate["Validate JSON syntax + Schema + Naming"]
Validate --> Rename["Assign sequential <category>/json/<name>_<index>.json"]
Rename --> OpenPR["Create PR & Rebuild index.min.json"]
OpenPR --> CheckAuth{"Author is Collaborator?"}
CheckAuth -->|Yes| AutoMerge["Enable Auto-Merge (Squash)"]
CheckAuth -->|No| Review["Await Maintainer Review & Approval"]
AutoMerge --> Merge["Merged to main"]
Review -->|Approved & Merged| Merge
Merge --> BuildIndex["GitHub Action: build-index.yml"]
BuildIndex --> CDN["Published to GitHub Pages & jsDelivr CDN"]
- Collaborators: PRs opened from maintainer submissions are validated and automatically scheduled for auto-merge.
- Community Submissions: PRs are opened for maintainer review, preventing unverified or malformed code from landing directly on
main.
The catalog is distributed dynamically via GitHub Pages (immediate updates) and accelerated via jsDelivr CDN (global edge caching). No repository owner is hardcoded.
- GitHub Pages (Dynamic Catalog with immediate ETag updates):
https://<owner>.github.io/<repo>(e.g.https://kytyps5.github.io/KytyPS5-Modules) - jsDelivr CDN (Fast Global Edge Caching for static assets):
https://cdn.jsdelivr.net/gh/<owner>/<repo>@main(e.g.https://cdn.jsdelivr.net/gh/KytyPS5/KytyPS5-Modules@main)
export interface CatalogIndex {
version: number;
catalogHash: string; // 64-char SHA-256 hash of entire catalog
updatedAt: string; // ISO-8601 timestamp
patches: Record<string, ModuleEntry[]>; // Keyed by Title ID (e.g. "PPSA01325")
cheats: Record<string, ModuleEntry[]>;
configs: Record<string, ModuleEntry[]>;
}
export interface ModuleEntry {
id: string; // PS5 Title ID, e.g. "PPSA01325"
version: string; // Display version, e.g. "01.905.000"
gameName: string; // Human-readable game title
index: number; // Sequential counter (1, 2, ...)
title: string; // Mod or patch title
description: string; // Patch notes or usage instructions
author: string; // Submitter or creator
path: string; // Relative path: "patches/json/<filename>.json"
sha256: string; // SHA-256 hash of canonical LF content
size: number; // Byte length
}
export interface MemoryPatch {
offset: string; // Hex address, e.g. "0x73eb993"
on: string; // Replacement hex bytes
off: string; // Original hex bytes
}
export interface ModItem {
name: string;
enabled: boolean;
memory?: MemoryPatch[];
}
export interface PatchModule {
id: string;
name: string;
version: string;
process?: string; // Target executable, e.g. "eboot.bin"
source_sha256?: string;
mods?: ModItem[];
}import { createHash } from "node:crypto";
class KytyModuleManager {
private repoOwner: string;
private repoName: string;
private cachedEtag: string | null = null;
private catalog: CatalogIndex | null = null;
constructor(repoOwner: string = "KytyPS5", repoName: string = "KytyPS5-Modules") {
this.repoOwner = repoOwner;
this.repoName = repoName;
}
get pagesBaseUrl(): string {
return `https://${this.repoOwner}.github.io/${this.repoName}`;
}
get cdnBaseUrl(): string {
return `https://cdn.jsdelivr.net/gh/${this.repoOwner}/${this.repoName}@main`;
}
/**
* Fetches the catalog manifest using HTTP ETag caching.
* If unchanged, the server returns HTTP 304 and cached data is reused.
*/
async refreshCatalog(): Promise<CatalogIndex> {
const headers: Record<string, string> = {};
if (this.cachedEtag) {
headers["If-None-Match"] = this.cachedEtag;
}
const res = await fetch(`${this.pagesBaseUrl}/index.min.json`, { headers });
if (res.status === 304 && this.catalog) {
// Catalog unchanged; reuse memory cache
return this.catalog;
}
if (res.ok) {
this.cachedEtag = res.headers.get("etag");
this.catalog = (await res.json()) as CatalogIndex;
return this.catalog;
}
throw new Error(`Failed to fetch catalog: HTTP ${res.status}`);
}
/**
* Lazy-loads and verifies a module JSON file on demand.
*/
async fetchModule(entry: ModuleEntry): Promise<PatchModule> {
const res = await fetch(`${this.cdnBaseUrl}/${entry.path}`);
if (!res.ok) {
throw new Error(`Failed to download ${entry.path}: HTTP ${res.status}`);
}
const rawText = await res.text();
// Normalize to LF before computing SHA-256 to ensure cross-platform hash parity
const normalizedBytes = Buffer.from(rawText.replace(/\r\n/g, "\n"), "utf8");
const actualHash = createHash("sha256").update(normalizedBytes).digest("hex");
if (actualHash !== entry.sha256) {
throw new Error(
`Integrity check failed for ${entry.path}! Expected: ${entry.sha256}, Got: ${actualHash}`
);
}
return JSON.parse(rawText) as PatchModule;
}
}# Run complete test suite (unit + integration)
npm test
# Validate all module files against schema and naming regex
npm run validate
# Rebuild index.json and index.min.json
npm run build:index
# Run all verification steps in sequence
npm run check