NeoCore

🎯 Overview

NeoCore is a library and toolchain for developing on Neo Geo CD.

It provides high-level functions over Neo Dev Kit and DATlib 0.3, and includes tools and code that can help with projects on this platform.

✨ Key Features

🚀 High abstraction level for Neo Geo CD development
🔧 Toolchain with PowerShell scripts
🎮 Compatible with Windows 11
📖 Documentation generated with Doxygen
🔄 Hot reload for rapid development

🔗 Quick Links

⚠️ Upgrading from v2.x? This version includes breaking changes. Please check the migration guide before upgrading from NeoCore 2.x to 3.x.

📚 Table of Contents

🎯 Overview
📋 Requirements
📅 Roadmap
🚀 Quick Start
⚙️ Command Reference
🔧 Development Workflow
- C89/ANSI C Strict Compliance
- Build Steps (v3.0.0+)
📦 Project Management
📖 Documentation & Resources
- 📚 C API Documentation
- 🎨 DATlib Assets
📊 Profiling
🎵 Audio Configuration
🛠️ Advanced Development
🤝 Contribution
- 🎮 Game Examples & Showcases
📚 Dependencies

Requirements

Up to date Windows 11
Git https://git-scm.com/download/win
Windows Terminal with cmd instance (shortcut win + r and type wt cmd)

📅 Roadmap

🟢 Completed (v3.4.0)

✅ neocore version switcher script for standalone projects
✅ One-liner command for project creation
✅ Mak lint command for project validation
✅ Integrate city41/mameNeoGeoDevPlugin (use \.\mak.bat run:mame:debug to enable it)
- ✅ Fork and tweak for NeoCore - neocore-mameNeoGeoDevPlugin
- ✅ Add Windows compatibility
- ✅ Add Neo-Geo CD MAME compatibility
- ✅ Upgrade MAME for plugin API compatibility

🟢 Completed (v3.4.1)

✅ Upgrade Raine emulator to 0.97.5
✅ Fix issue 211: Incorrect CUE file paths when generating ISO with MP3 CDDA tracks (mak dist:iso)

🟢 Completed (v3.4.3)

✅ DATlib JobMeter
- ✅ Sample demo: job_meter
✅ Automatic generation of a structure aggregating a pointer to sprite data in ROM
and a pointer to palette information in ROM during sprite compilation

🟡 In Progress

🔵 Planned - Soon

🔜 Runtime palette creation: instantiate sprites with palettes built in RAM (may be delayed after NeoCore 4)

🔵 Planned - Later

🔜 NeoCore 4
- Remove deprecated functions, macros and structures since NeoCore 3.1.1
- Refactor nc_gfx* functions
🔜 AES / MVS support (5% completed)
- ✅ Externalized CDDA functions (completed in v3.4.4)
- ✅ Added auto-generated out/platform.h to define the platform type (CD or Cartridge) (completed in v3.4.4)
- 🔜 Lib CD Makefile
- 🔜 Lib Cartridge Makefile
- 🔜 Generate hash and rom file for Mame
🔜 Add basic modular C lib system for reusable functions and assets
🔜 RGB palette handlers (60% completed)
- Samples: pal_backdrop, pal_rgb, pal_rgb_mixer
🔜 Joypad 2 support
🔜 Improve sound FX management
- Evaluate Mezz-Estate-NeoGeo-Audio-Driver
🔜 Palette bank switcher
🔜 DRAM asset management (unload/load from CD-ROM)

🧐 Under Consideration

💭 Split project.xml to separate user parameters from toolchain parameters
💭 Video recording support (MAME MNG format with manual ffmpeg conversion to MP4)
💭 XML WYSIWYG editor
💭 Memory card support
💭 CLI-based asset packager
💭 Split project.xml to separate user parameters from toolchain parameters
💭 GCC upgrade to version > 2.95.2
- Evaluate DATlib → libNG (TheHpman/libNG)
💭 Raine version selection
💭 MAME version selection

🚀 Quick Start

Which method should I use?

🟢 Most users: No cloning required!

If you want to create your own NeoGeo CD game or app, you do NOT need to clone this repository.

👉 Just use the one-liner below to initialize your project. This will always fetch the latest stable version and set up everything for you automatically.

🛠️ When should you clone the repo?

You only need to clone this repository if you want to:

Explore or run the included samples and demos
Contribute to the NeoCore toolchain or C library
Develop, debug, or customize the NeoCore internals

For 99% of new projects, the one-liner is all you need!

Three-Step Setup

2️⃣ Create Your Project

💡 No need to clone or download NeoCore - the script does everything for you!

⚠️ Avoid spaces in paths (use C:\MyGame not C:\My Game)

md C:\MyGame && cd C:\MyGame

curl -L https://raw.githubusercontent.com/David-Vandensteen/neocore/master/bootstrap/scripts/project/create_from_oneliner.bat -o c.bat && c.bat && del c.bat

cd src

.\mak.bat sprite && .\mak.bat && .\mak.bat run:mame

3️⃣ Next Steps

📖 Important: Review C89 Compliance rules before coding
📋 See Command Reference for all build commands
🎮 Explore Custom Emulator Profiles for testing
🗂️ Read Project Management for advanced project setup

⚙️ Command Reference

⚠️ Warning: The mak script overrides the PATH environment variable during compilation. If you encounter any problems after using it, simply close and restart a new command terminal.

🔨 Development Cycle

Building:

Command	Description
`.\mak.bat sprite`	Build sprites from assets
`.\mak.bat`	Compile C code and link
`.\mak.bat lib`	Compile NeoCore library
`.\mak.bat clean`	Remove built resources
`.\mak.bat clean:build`	Remove entire build folder

Testing:

Command	Description
`.\mak.bat run:raine`	Run with Raine emulator
`.\mak.bat run:mame`	Run with MAME emulator
`.\mak.bat run:mame:debug`	Run with MAME in debug mode (ngdev plugin)
`.\mak.bat serve:mame`	Run in hot reload mode

🧪 Validation & Tools

Command	Description
`.\mak.bat lint`	Validate project (project.xml, .gitignore, legacy code)
`.\mak.bat framer`	Launch DATlib Framer
`.\mak.bat animator`	Launch DATlib Animator

📦 Distribution

Command	Description
`.\mak.bat dist:iso`	Create ISO distribution package
`.\mak.bat dist:mame`	Create MAME distribution package
`.\mak.bat dist:exe`	Create Windows standalone executable

ℹ️ Information

Command	Description
`.\mak.bat --version`	Display version information

🎮 Custom Emulator Profiles

You can create custom emulator profiles for different testing scenarios. NeoCore comes with default profiles (default, full, nosound, debug for MAME), but you can add your own.

Creating Custom MAME Profiles:

Add custom profiles to your project.xml:

<project>
  <emulator>
    <mame>
      <profile>
        <!-- Default profiles are already included -->
        <myprofile>-window -skip_gameinfo -throttle neocdz</myprofile>
        <benchmark>-window -skip_gameinfo -nothrottle -bench 60 neocdz</benchmark>
        <record>-window -skip_gameinfo -aviwrite output.avi neocdz</record>
      </profile>
    </mame>
  </emulator>
</project>

Creating Custom Raine Configurations:

Create custom config files in your project and reference them:

<project>
  <emulator>
    <raine>
      <config>
        <!-- Default configs are already included -->
        <myconfig>raine\config\myconfig.cfg</myconfig>
        <test>raine\config\test.cfg</test>
      </config>
    </raine>
  </emulator>
</project>

Usage:

# Use your custom MAME profiles
.\mak.bat run:mame:myprofile
.\mak.bat run:mame:benchmark
.\mak.bat run:mame:record

# Use your custom Raine configs
.\mak.bat run:raine:myconfig
.\mak.bat run:raine:test

# Default profiles (included with NeoCore)
.\.mak.bat run:mame:full      # Fullscreen
.\mak.bat run:mame:debug     # Debug mode with ngdev plugin
.\mak.bat run:raine:full     # Fullscreen

🐞 Debug Mode with ngdev Plugin

The debug profile provides enhanced Neo Geo CD debugging capabilities:

.\mak.bat run:mame:debug

Plugin Information:

Automatically installed
Based on city41/mameNeoGeoDevPlugin
Forked and enhanced for NeoCore: neocore-mameNeoGeoDevPlugin
Profile is automatically maintained by NeoCore

🔧 Development Workflow

C89/ANSI C Strict Compliance

⚠️ CRITICAL: This project uses gcc-2.95.2 and requires strict C89 (ANSI C) compliance.

Key Rules:

Declare all variables at the beginning of blocks
Declare loop variables outside loops
No mixed declarations and code

📖 Click for C89 compliance examples

1. All variables must be declared at the beginning of blocks:

/* ✅ CORRECT */
int function(void) {
    int i;
    char* buffer;

    i = 0;
    buffer = NULL;
    /* code here */
}

/* ❌ WRONG - will not compile */
int function(void) {
    int i = 0;
    doSomething();
    char* buffer = NULL;  /* ERROR: declaration after statement */
}

2. Loop variables must be declared outside loops:

/* ✅ CORRECT */
int i;
for (i = 0; i < 10; i++) {
    /* code */
}

/* ❌ WRONG */
for (int i = 0; i < 10; i++) {  /* ERROR: C99+ feature */
    /* code */
}

3. No inline variable initialization in declarations (unless constant):

/* ✅ CORRECT */
int x;
x = getValue();

/* ❌ WRONG (unless getValue() is a constant) */
int x = getValue();

Build Steps (v3.0.0+)

Starting with version 3.0.0, build steps are now explicit and must be executed manually for better control and performance optimization:

Development Workflows

# Initial development (build everything)
.\mak.bat sprite && .\mak.bat && .\mak.bat run:raine

# Code-only modifications (sprites unchanged)
.\mak.bat && .\mak.bat run:raine  # ⚡ Faster!

# Quick test without recompilation
.\mak.bat run:raine  # 🚀 Instant!

Build Step Breakdown

Step	Command	Purpose	When to use
1. Sprites	`.\mak.bat sprite`	Generate sprite data from assets	When assets change
2. Compile	`.\mak.bat`	Compile C code and link	When code changes
3. Run	`.\mak.bat run:raine`	Launch in emulator	Always for testing

Performance Benefits

🚀 Faster iteration: Skip sprite generation when only code changes
💾 Cache optimization: Leverage build cache for unchanged components
🎯 Granular control: Build only what you need
⏱️ Reduced build time: Avoid unnecessary regeneration

Migration Note: In versions before 3.0.0, mak run:raine or mak run:mame automatically executed all build steps.
This workflow change provides better performance for iterative development.

📦 Project Management

🆙 Upgrade an Existing Project

⚠️ Important: Backup your project before upgrading. Check the migration guide for breaking changes.

Method 1: Using Version Switcher (NeoCore 3.2.0+)

The version switcher provides a simple way to upgrade or switch between NeoCore versions:

# From your project root directory
cd C:\temp\MyGame

# Upgrade to latest stable version
.\neocore-version-switcher.bat master

# Or switch to a specific version
.\neocore-version-switcher.bat 3.2.0

# List all available versions
.\neocore-version-switcher.bat --list

Method 2: Manual Upgrade Script (NeoCore < 3.2.0)

# 1. Remove build folder
rd /S /Q C:\temp\MyGame\build

# 2. Run upgrade script
cd <neocore>\bootstrap\scripts\project
.\upgrade.bat -projectSrcPath C:\temp\MyGame\src -projectNeocorePath C:\temp\MyGame\neocore

📤 Release a Project

From your project's src folder:

# ISO distribution
.\mak.bat dist:iso

# MAME distribution
.\mak.bat dist:mame

# Windows standalone executable (game + emulator)
.\mak.bat dist:exe

📖 Documentation & Resources

📚 C API Documentation

Doxygen Documentation
Migration Guide - Breaking changes and migration from previous versions
Changelog - Version history

🎨 DATlib Assets

DATlib Documentation:

DATlib Reference (PDF)

Configuration in project.xml:

<project>
  <gfx>
    <DAT>
      <chardata>
        <!-- DATlib configuration -->
      </chardata>
      <fixdata>
        <!-- DATlib fixdata configuration -->
      </fixdata>
    </DAT>
  </gfx>
</project>

DATlib Tools:

.\mak.bat framer     # Launch DATlib Framer
.\mak.bat animator   # Launch DATlib Animator

📊 Profiling

Job Meter - CPU Profiling Tool

The Job Meter is a visual profiling tool from DATlib that helps developers understand CPU time distribution across different parts of their game loop. It displays a color-coded vertical bar on the right side of the screen, showing which operations are consuming frame time.

Key Features:

🎨 Color-coded profiling: Each color represents a different operation
📊 Real-time visualization: See CPU usage live as your game runs
🎯 Performance optimization: Identify bottlenecks quickly

Quick Start:

#include <neocore.h>

/* Initialize job meter after sprite setup */
jobMeterSetup(true);

while(1) {
    /* Mark input handling section */
    jobMeterColor(JOB_CYAN);
    nc_gpu_update();
    
    /* Your input handling code */
    
    /* Mark scrolling section */
    jobMeterColor(JOB_YELLOW);
    /* Your scrolling code */
    
    /* Mark animation section */
    jobMeterColor(JOB_BLUE);
    /* Your animation code */
    
    /* Free CPU time */
    jobMeterColor(JOB_GREEN);
}

Important Notes:

⚠️ Debug Only: Job meter should only be used in debug builds. On real hardware, changing colors during active display creates visible pixel artifacts.

⚠️ Initialization Order: jobMeterSetup() must be called AFTER sprite and graphics initialization, not as the first function.

Complete Example:

Check the job_meter sample for a fully interactive demonstration with:

Real-time CPU load adjustment
Multiple profiling sections
Visual feedback and color reference
Configurable artificial overhead

Learning Resources:

📚 Job Meter Sample - Complete interactive example
📖 DATlib Reference (PDF) - Full DATlib documentation

🎵 Audio Configuration

CDDA (CD Digital Audio) Configuration

Quick Facts:

Track ID 1 is reserved for the binary program
Use WAV files for source audio (automatic MP3 conversion for distribution)
Mixed source formats supported (WAV, MP3)

📖 Click for complete CDDA configuration example

Configuration structure:

<project>
  <sound>
    <cd>
      <cdda>
        <dist>
          <iso>
            <format>mp3</format>  <!-- Distribution format -->
          </iso>
        </dist>
        <tracks>
          <track><!-- track id 1 is reserved for the binary program -->
            <id>2</id>
            <file>assets\sounds\cdda\track02.wav</file>
            <pregap>00:02:00</pregap>
          </track>
          <!-- Add more tracks as needed -->
        </tracks>
      </cdda>
    </cd>
  </sound>
</project>

Audio file organization:

assets/
└── sounds/
    └── cdda/
        ├── track02.wav
        ├── track03.wav
        └── track04.mp3

Notes:

Pregap of 00:02:00 is standard for CD audio
Distribution format (MP3) optimizes ISO size

🤝 Contribution

🎯 How to Contribute

Developers:

📝 Create tutorials or code examples
🐛 Report and fix bugs
💡 Propose new features
📚 Improve documentation

Neo-Geo CD Owners:

🧪 Test examples on real hardware
🐛 Report hardware compatibility issues
✅ Confirm functionality on real hardware

Financial Support: To improve hardware compatibility and project development, any financial contribution is appreciated.

💰 Make a PayPal donation

⚠️ Disclaimers

This project is under active development
Mainly tested on Raine and MAME emulators
No guarantee of functionality on real Neo-Geo hardware
The author is not responsible for any software damage

Any help is welcome! 🙏

🎮 Game Examples & Showcases

Pong: https://github.com/David-Vandensteen/neogeo-cd-pong
Flamble:

🛠️ Advanced Development

♻️ Hot Reload

Hot reload allows you to automatically recompile and restart your project when making changes:

cd <neocore>\samples\hello
.\mak.bat serve:mame

The emulator launches
Edit main.c
Save the file
The project recompiles and restarts automatically

Current limitations:

⚠️ Not a real watcher (triggers only when folder size changes)
⚠️ PATH is not restored when interrupted (close/reopen terminal)

🔧 Compile Library

Necessary if you modify NeoCore source code:

.\mak.bat clean
.\mak.bat lib

🌿 Branches & Versions

⚠️ Important: Remove the .\neocore\build folder before compiling after a branch change to avoid cache conflicts.

.\mak.bat clean:build

📚 Dependencies

Core Development Tools

GCC - C compiler (version 2.95.2 for C89 compliance)
MSYS2 - Unix-like environment for Windows
Git - Version control (required for installation)

Neo Geo Development

NeoDev - Neo Geo CD development toolkit
DATlib - Data library for Neo Geo assets
DATimage - Image processing for Neo Geo graphics
NGFX SoundBuilder - Audio tool for Neo Geo sound effects

Emulators & Testing

Raine - Neo Geo CD emulator
MAME - Multi-platform emulator (version 0.251)
city41/mameNeoGeoDevPlugin - Enhanced MAME debugging (ngdev fork)

Build & Distribution Tools

Mkisofs - ISO image creation
NSIS - Windows installer creation
mpg123 - MP3 decoder
ffmpeg - Audio/video conversion

Documentation

Doxygen - API documentation generation

📝 Changelog

Complete version history and changes documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 1,940 Commits
bootstrap		bootstrap
docs		docs
doxygen		doxygen
samples		samples
src-lib		src-lib
tests		tests
toolchain		toolchain
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
manifest.xml		manifest.xml

David-Vandensteen/neocore

Folders and files

Latest commit

History

Repository files navigation