Skip to content
BranchesTags

Repository files navigation

Dungeoncore Necromancer — Serialized Novel Platform

Deploy to GitHub Pages CI Next.js 16 React 19 TypeScript Tailwind CSS 4 Bun License: MIT

A serialized-novel reading platform and narrative world engine built with Next.js 16 (App Router) and Web Audio synthesis. Seven arcs. Sixty-three chapters. One truth, buried under twenty-seven thousand loops.

The reader begins where the protagonist awakens — an animal consciousness trapped in a subterranean core that is also its own body — and the interface itself evolves as the story deepens from dungeon-management dark fantasy into cosmic existential tragedy.

Single Curated Void Aesthetic: The platform ships with a unified, meticulously calibrated dark aesthetic. Contrast, typography, and luminance are tuned for immersive, distraction-free reading during long sessions.

Table of Contents

Features

  • 63-Chapter Manuscript — Complete prose for initial chapters and structured narrative treatment outlines across all 63 chapters.
  • 7-Arc Narrative Architecture — Expandable chapter lists tagged with boss encounters, climax milestones, and temporal anchors.
  • Interactive World Codex — Comprehensive 8-faction compendium, deep chronological timeline, and antagonist profiles.
  • Craft & Endings Registry — Live-filtered foreshadowing index tracking story threads across all arcs alongside three terminal outcome vectors.
  • Unified Command Palette (⌘K / Ctrl+K) — High-speed fuzzy search across all sections, chapters, factions, chronology events, antagonist dossiers, and foreshadowing entries with contextual excerpts.
  • Customizable Reading Engine — Switch between Serif, Sans, and Monospace typography, adjust font scale, customize column widths, modify line height, and toggle distraction-free Focus Mode.
  • Progress Tracking & Bookmarks — Automatic per-chapter scroll progress saving, resume-reading prompts, and mark-as-read toggles backed by localStorage.
  • Native Print-to-PDF Engine — Clean print stylesheet (@media print) that isolates prose onto pristine, readable white pages and strips all chrome.
  • Generative Ambient Music Synthesizer — Six real-time procedural soundscapes created directly in browser memory using the Web Audio API with zero external audio assets.
  • Full Accessibility (WCAG AA) — Keyboard navigation, focus trapping, ARIA live region announcements, and reduced-motion query support.
  • Zero Server Runtime — 100% static export (output: "export") deployable to GitHub Pages, Cloudflare Pages, Netlify, or any static hosting service.

Platform Views

View Description Key Capabilities
Overview Narrative architecture and map 7-arc structure, chapter status indicators, core stats, quick-jump links
Manuscript Core reading interface Chapter reader, progress indicator, reading settings, PDF export, prev/next chapter navigation
World Codex Worldbuilding and lore archive 8 interactive factions, chronological events timeline, antagonist dossiers
Craft & Endings Writer's craft and story architecture Foreshadowing matrix with status filters, terminal loop outcome vectors
Easter Eggs Secret layers & terminal logs Reality stability monitor, unlockable narrative logs, glyph resonance

Generative Audio Engine (Web Audio API)

The built-in ambient player generates procedural audio landscapes in real time directly on the client's audio device:

Soundscape Narrative Alignment Root Frequency Harmonics & Waveform Filter & Space
The Deep Blue Submarine · Atmospheric · Arc I 55.0 Hz (A1) Sine · [1, 1.5, 2, 3] 800 Hz LPF · 35% Convolver
Ancient Stone Ambient · Meditative · Arc I–II 65.4 Hz (C2) Triangle · [1, 1.25, 2, 2.5, 4] 600 Hz LPF · 45% Convolver
The Procession Tense · Marching · Arc II 49.0 Hz (G1) Sawtooth · [1, 1.5, 2.01, 3, 4.02] 500 Hz LPF · Filtered Noise
Contradictions Uneasy · Detuned · Arc III 58.27 Hz (A♯1) Triangle · [1, 1.06, 1.5, 2.83, 4.24] 900 Hz LPF · 15¢ Detune
Cosmic Drift Cinematic · Vast · Arc V–VI 41.2 Hz (E1) Sine · [1, 1.5, 2, 3, 4, 6] 1200 Hz LPF · 60% Convolver
The Lullaby Ethereal · Melancholic · Arc VII 73.42 Hz (D2) Triangle · [1, 1.2, 1.5, 2, 3] 1500 Hz LPF · Slow LFO Drift

DSP Synthesis Graph

Oscillators (Harmonic Stack) ──► Lowpass Filters ──► LFO Modulators ──┐
                                                                       ▼
Noise Generator ───────────────► Noise Filter ────► Noise Gain ──► Soundscape Master Gain
                                                                            │
               ┌────────────────────────────────────────────────────────────┴────────────────────────┐
               ▼                                                                                     ▼
       Shared Dry Send                                                                       Convolver Reverb
               │                                                                                     │
               ▼                                                                                     ▼
       Master Output Node ◄────────────────────────────────────────────────────────────── Reverb Gain Node
               │
               ▼
       Dynamics Compressor / Limiter ──► Audio Destination (Speakers / Headphones)

Interactive Secrets & Easter Eggs

The platform features multiple hidden interaction layers embedded within the interface:

  • The Konami Code: Enter ↑ ↑ ↓ ↓ ← → ← → B A anywhere on the site to trigger the Cosmic Decay overlay.
  • The Core Glyph: Click the header glyph icon 7 times in succession to reveal hidden protagonist memories.
  • The Lullaby Resonance: Type lullaby anywhere on the keyboard to automatically tune the procedural audio engine to Arc VII's harmonic theme.
  • Reality Stability Meter: Reader interactions, loop transitions, and secret discoveries dynamically adjust the systemic reality stability value.

Keyboard Shortcuts

Shortcut Action
⌘ K / Ctrl K Open Search / Command Palette
⌘ . / Ctrl . Toggle Reading Settings Drawer
F Toggle Focus Mode (distraction-free reading)
? / Shift / Open Keyboard Shortcuts Cheatsheet
← / → Jump to Previous / Next Chapter (in Manuscript)
Esc Dismiss overlays, drawers, and modal panels

Tech Stack

Layer Technology
Framework Next.js 16 (App Router, Turbopack, Static Export)
UI Library React 19
Language TypeScript 5
Styling Tailwind CSS 4 + PostCSS
State Management Zustand 5 (with persist middleware)
Icons Lucide React
Typography Playfair Display, Literata, JetBrains Mono (next/font)
Runtime & Package Manager Bun (compatible with Node.js ≥ 20)
CI / CD & Deployment GitHub Actions + GitHub Pages

Project Structure

Dungeoncore-Necromancer/
├── .github/
│   └── workflows/
│       ├── ci.yml                 # Lint and test static build on pull requests
│       └── deploy.yml             # Automatic build and deployment to GitHub Pages
├── .vscode/                       # VS Code workspace settings, tasks, and debug configs
├── public/
│   ├── .nojekyll                  # Prevents GitHub Pages from stripping _next assets
│   ├── art/                       # Chapter artwork and visual assets
│   ├── favicon.svg                # Vector site icon
│   └── site.webmanifest           # Progressive web app manifest
├── src/
│   ├── app/
│   │   ├── globals.css            # Tailored theme tokens, typography, and print styles
│   │   ├── layout.tsx             # Root layout with font optimization and metadata
│   │   └── page.tsx               # Primary application orchestrator and event hub
│   ├── components/
│   │   ├── ErrorBoundary.tsx      # Application error boundary
│   │   └── dungeoncore/           # Modular reader components & views
│   │       ├── views/             # Overview, Manuscript, World, Craft, EasterEggs views
│   │       ├── Boot.tsx           # Hydration boot animation and preloader
│   │       ├── CommandPalette.tsx # ⌘K fuzzy archive search
│   │       ├── MusicPlayer.tsx    # Web Audio real-time DSP synthesizer
│   │       ├── SettingsPanel.tsx  # Typography, scale, and layout customization
│   │       └── TopBar.tsx         # Navigation header and progress indicator
│   └── lib/
│       ├── asset.ts               # Base-path URL resolver for GitHub Pages subpaths
│       ├── story-data.ts          # Typed manuscript data, lore codex, and chapter registry
│       └── dungeoncore/           # Zustand store, hooks, search engine, and soundscapes
├── next.config.ts                 # Next.js configuration (static export, base paths)
├── package.json                   # Dependencies and scripts
└── tsconfig.json                  # TypeScript compiler configuration

Quick Start & Local Development

Prerequisites

1. Clone the Repository

git clone https://github.com/Pushyanth02/Dungeoncore-Necromancer.git
cd Dungeoncore-Necromancer

2. Install Dependencies

Using Bun (recommended):

bun install

Using npm:

npm install

3. Start the Development Server

bun run dev
# or: npm run dev

Open http://localhost:3000 in your browser.

4. Build and Lint

# Run ESLint check
bun run lint

# Build static production export into `out/`
bun run build

Deployment to GitHub Pages

This project is configured for automated, zero-configuration static deployment to GitHub Pages via GitHub Actions.

How It Works

  1. When changes are pushed to the main branch, .github/workflows/deploy.yml triggers automatically.
  2. The workflow installs dependencies via Bun, executes actions/configure-pages@v5 to determine the repository base path, and runs bun run build.
  3. Next.js statically exports the application to the out/ directory with output: "export".
  4. A .nojekyll file is verified in out/ so GitHub Pages serves _next/ static bundles without interference.
  5. The out/ artifact is uploaded and deployed to GitHub Pages.

Enabling GitHub Pages in Your Repository

  1. On GitHub, navigate to your repository's Settings tab.
  2. Under Code and automation, click Pages.
  3. Under Build and deployment > Source, select GitHub Actions.
  4. Push to main or manually trigger the Deploy to GitHub Pages workflow under the Actions tab.

Architecture & Design Principles

  • Hydration Safety: State persistence uses Zustand with skipHydration: true. An explicit rehydrate() runs on mount while the Boot component prevents flash of unstyled content or hydration mismatch.
  • Zero Asset Audio: Ambient audio relies completely on Web Audio oscillators, biquad filters, and procedural impulse responses, keeping bundle size minimal and avoiding external asset network requests.
  • Isolated Asset Resolution: All static asset references pass through asset(path) from src/lib/asset.ts, which automatically handles root-domain deployments as well as subpath-hosted GitHub Pages (https://<user>.github.io/<repo>/).
  • Separation of Concerns: Narrative prose, character codex, chronology data, and system settings exist as pure typed data models in src/lib/story-data.ts, decoupled from React presentation components.

Contributing

Contributions, bug reports, and suggestions are welcome! Please check .github/CONTRIBUTING.md for contribution guidelines, branch conventions, and development workflows.

License

This project is open source and available under the MIT License.

About

A serialized-novel reading platform and narrative world engine built with Next.js 16 (App Router) and Web Audio synthesis. Seven arcs. Sixty-three chapters. One truth, buried under twenty-seven thousand loops.

pushyanth02.github.io/Dungeoncore-Necromancer/

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages