Developer_Onboarding

Project-DJ-Engine (PDJE) is a soft real-time C++ engine for DJ-style audio playback, note-chart authoring, low-latency input capture, and rhythm-game judgment. This page is the shortest path to a correct mental model before you jump into generated API pages or source files.

What PDJE Is

PDJE is organized around four integration surfaces:

  • PDJE the main facade for playback, editor access, and the core data line.

  • PDJE_Input low-latency keyboard, mouse, and MIDI ingestion.

  • PDJE_JUDGE::JUDGE timing-sensitive note matching built on synchronized input and audio clocks.

  • PDJE_UTIL reusable utility code for status handling, storage abstractions, and helper functions.

Choose Your Starting Path

  • If you need playback, player control, or track/music lookup, start with Core_Engine.

  • If you need to author or edit project content, read Core_Engine for the entrypoints, then move to Editor_Workflows.

  • If you need keyboard, mouse, or MIDI input capture, read Input_Engine.

  • If you are building rhythm-game style timing and scoring, read Judge_Engine after Input_Engine.

  • If you need shared live state between modules, read Data_Lines.

  • If you need editor data formats or timeline serialization details, read Editor_Format after Editor_Workflows.

  • If you need non-C++ bindings, read Core_Engine first, then use the wrapper notes there to distinguish SWIG bindings from Godot-facing wrappers.

How To Read This Project

Recommended reading order:

  1. Read Project-DJ-Engine – A Real‑Time Engine for Rhythm Games, DJing, and Audio Production for the high-level module overview. It also now carries the broader use-case and project-automation context.

  2. Read Getting Started for the guide map.

  3. Read Core_Engine to understand the main facade and runtime flow.

  4. Read Editor_Workflows if your application creates or mutates project content.

  5. Read Input_Engine if your application touches live input.

  6. Read Judge_Engine if your application performs note matching.

  7. Read Data_Lines before you poll live state from another module or thread.

  8. Read Editor_Format if you generate or inspect editor-side data on disk.

  9. Use API Reference only after the workflow docs above.

The hand-written docs explain recommended workflows. The generated API explains what symbols exist. Those are not the same thing.

Build And Configuration Reality

Current build facts from the source tree:

  • CMake minimum is 3.12.

  • The project requires C++20.

  • Conan is part of the expected dependency flow through conan_cmakes/conan_toolchain.cmake.

  • PDJE_DYNAMIC controls static vs shared library builds.

  • PDJE_DEVELOP_INPUT controls whether the input and judge module libraries are built.

  • PDJE_SWIG_BUILD enables the SWIG wrapper targets.

  • PDJE_TEST enables doctest-based unit tests and CTest registration.

  • PDJE_DEV_TEST enables legacy/manual developer test executables.

Practical meaning:

  • PDJE itself is the always-built core library.

  • PDJE_MODULE_INPUT and PDJE_MODULE_JUDGE exist only when PDJE_DEVELOP_INPUT=ON.

  • On Windows, enabling the input path also enables the subprocess executable used by the Raw Input transport.

  • The current tree carries production input implementations for Linux and Windows.

  • macOS input is not implemented in-tree.

Project Mental Model

  • Core runtime facade lives under include/core/ and exposes the main public entrypoint include/core/interface/PDJE_interface.hpp.

  • Editor and authoring subsystem also lives under include/core/, but spans both include/core/MainObjects/editorObject/ and include/core/editor/. It is a major part of the project, not just a helper around InitEditor().

  • Input lives under include/input/ and exposes include/input/PDJE_Input.hpp.

  • Judge lives under include/judge/ and exposes include/judge/PDJE_Judge.hpp.

  • Utility lives under include/util/ and exposes include/util/PDJE_Util.hpp.

  • Global shared infrastructure lives under include/global/ and provides data lines, clocks, crypto, RAII, and logging helpers used across modules.

The tree also contains older or legacy areas such as trashbin and DEPRECATE. Do not assume those are active build paths just because they appear in generated API pages.

Useful Domain Knowledge

DJ and playback terms:

  • music usually means a concrete audio asset plus metadata.

  • track usually means a higher-level authored object that can reference mix and note structures plus music metadata.

  • deck means a playback slot or source lane inside a DJ-style workflow.

  • cue means a specific seek/play start position.

  • BPM is beats per minute and appears in both playback and chart timing contexts.

  • FX means runtime effect processing such as filter, EQ, echo, or roll.

Rhythm-game terms:

  • rail is the gameplay lane or logical input destination a note belongs to.

  • note is an authored gameplay event with timing and rail metadata.

  • judgment window means the timing tolerance around the expected note time.

Audio timing terms:

  • frame means one sample frame at the current sample rate.

  • sample rate controls how frame positions map to time.

  • callback cadence means how often the audio backend asks for more audio.

  • microsecond is the fine-grained timing unit used for synchronized input/audio judgment.

Input terms:

  • backend means the platform-specific input implementation that was selected.

  • MIDI port means a live hardware or virtual MIDI input endpoint.

  • input_arena means the keyboard/mouse transport exposed by PDJE_INPUT_DATA_LINE.

Storage and authoring terms:

  • root DB means the database root used by the core/editor path.

  • project-local editor state means the working timeline and metadata state managed by editorObject before content is pushed back into the root DB.

  • SQLite is used in the relational storage layer.

  • RocksDB is used in the key-value storage layer.

  • Cap’n Proto is used for binary translation/serialization in the core DB pipeline.

  • editor JSON means the timeline-oriented JSON representation described in Editor_Format.

First Real Workflows

Playback-first integration flow:

  1. Build the project with the desired options.

  2. Construct PDJE with the root database path.

  3. Search for music or track objects through SearchMusic() or SearchTrack().

  4. Create a player with InitPlayer().

  5. Pull a PDJE_CORE_DATA_LINE if another module needs live playback state.

  6. Add PDJE_Input only if you need live keyboard, mouse, or MIDI capture.

  7. Add PDJE_JUDGE::JUDGE only if you need synchronized note matching.

Editor-first authoring flow:

  1. Build the project with the desired options.

  2. Construct PDJE with the root database path.

  3. Initialize the editor through InitEditor().

  4. Acquire the editorObject through GetEditorObject().

  5. Create or open project content, then mutate it through the editor workflow.

  6. Render or push the result back toward the root DB.

  7. Optionally use preview playback through the editor/player bridge.

Use these pages for the detailed workflows:

Contributor Orientation

If you are modifying the repository rather than only embedding the engine, start here:

  • Main public facade: include/core/interface/PDJE_interface.hpp

  • Playback implementation: include/core/MainObjects/audioPlayer/

  • Editor facade object: include/core/MainObjects/editorObject/

  • Editor timeline, linter, and serialization core: include/core/editor/

  • Input implementation: include/input/

  • Judge implementation: include/judge/

  • Utility layer: include/util/

  • Shared infrastructure: include/global/

  • Tests: include/tests/

  • Manual docs: document_sources/*.rst

  • Generated API: document_sources/api/

Important project quirks:

  • In this repository, include/ is not headers-only. It also contains a large amount of implementation .cpp code.

  • Editor history, timeline mutation, and render/push logic are not fully described by the top-level PDJE header. Read the editor-specific paths and manual docs before changing that subsystem.

Common Mistakes

  • Do not assume the generated API pages define the recommended integration order.

  • Do not assume input and judge are always built. That depends on PDJE_DEVELOP_INPUT.

  • Do not assume SWIG bindings cover every native C++ subsystem. The current SWIG output is strongest on the core/editor path.

  • Do not assume editor support is only InitEditor() plus one or two helper calls. editorObject is a real subsystem with mutation, history, and persistence workflows.

  • Do not assume Editor_Format explains the full editor operation model. It explains data shapes, not the complete editing lifecycle.

  • Do not assume legacy or deprecated paths are part of the active runtime.

  • Do not assume macOS input support exists in the current source tree.

  • Do not mix Godot wrapper names with native C++ names when reading examples.

Where To Go Next