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

⚠️ Current Version: This version includes breaking changes. Please check the migration guide before updating your existing projects.

📚 Table of Contents

🎯 Overview
🚀 Quick Start
- 📋 Requirements
- ⚡ Installation
📦 Project Management
⚙️ Command Reference
- 🔨 Mak Rules
- 🎮 Emulator Profiles
📖 Documentation & Resources
🛠️ Advanced Development
🎵 Audio Configuration
🤝 Contribution

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

🟡 Soon

Custom HUD / Fix layer
- Upgrade to Neocore v3 with DATlib 0.3
AES / MVS support (5% completed)

🕓 Later

RGB palette handlers (60% completed)
- Samples: pal_backdrop, pal_rgb, pal_rgb_mixer
Joypad 2 support
Improve sound FX management
Palette bank switcher
DRAM asset management (unload/load from CD-ROM)

🧐 Maybe

🚀 Quick Start

⚡ Installation

1. Clone the repository

git clone https://github.com/David-Vandensteen/neocore.git
cd neocore

2. Test the installation

cd samples\hello
.\mak.bat sprite
.\mak.bat
.\mak.bat run:mame

3. Create your first project

cd <neocore>\bootstrap\scripts\project
.\create.bat -name MyGame -projectPath C:\temp\MyGame
cd C:\temp\MyGame\src
.\mak.bat sprite
.\mak.bat
.\mak.bat run:mame

🎉 Congratulations! You've created and launched your first Neo Geo CD project.

💡 Next Steps: See Project Management section for detailed project creation options and workflows.

⚙️ Command Reference

🔨 Mak Rules

⚠️ 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.

Command	Description
`.\mak.bat`	Build the program
`.\mak.bat clean`	Remove built resources
`.\mak.bat clean:build`	Remove the entire build folder
`.\mak.bat sprite`	Build sprites
`.\mak.bat run:raine`	Run with Raine emulator
`.\mak.bat run:mame`	Run with MAME emulator
`.\mak.bat serve:mame`	Run in hot reload mode
`.\mak.bat dist:iso`	Create ISO distribution package
`.\mak.bat dist:mame`	Create MAME distribution package
`.\mak.bat dist:exe`	Create Windows standalone executable
`.\mak.bat framer`	Launch DATlib Framer
`.\mak.bat animator`	Launch DATlib Animator
`.\mak.bat lib`	Compile Neocore library
`.\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
.\mak.bat run:raine:full     # Fullscreen

🔧 Development Workflow

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

🆕 Create a New Project

cd <neocore>\bootstrap\scripts\project
.\create.bat -name MyGame -projectPath C:\temp\MyGame

Available options:

-force: Overwrite existing files
-name: Project name
-projectPath: Destination path

🆙 Upgrade an Existing Project

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

# 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

The upgrade script performs comprehensive validation and updates:

Automatic validation:

📋 Verifies project structure and required files (including Makefile)
🔍 Analyzes C code for breaking changes and deprecated patterns
�️ Removes deprecated files (common_crt0_cd.s, crt0_cd.s)
�💾 Creates automatic backup before making changes
📝 Generates detailed migration logs

What gets updated:

✅ Neocore toolchain and C library
✅ Build scripts (mak.bat and mak.ps1)
✅ Project structure validation
✅ Deprecated file cleanup (automatic removal)
✅ XML project definition
❌ Your source code (manual migration needed - see logs for guidance)
❌ Project assets

💡 Tip: The script generates detailed logs showing breaking changes found in your code. Review these logs to understand what manual changes may be needed.

🔒 Security Note: Migration logs may contain absolute paths from your system. Review generated logs before sharing them publicly and consider adding *.log to your .gitignore if needed.

📤 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

🎵 Audio Configuration

CDDA (CD Digital Audio) Configuration

For Neo Geo CD projects, you can configure CDDA tracks in your project.xml:

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>

Key points:

Track ID 1 is reserved for the binary program
Use WAV files for source audio (high quality)
Distribution format (MP3) optimizes ISO size
Pregap of 00:02:00 is standard for CD audio
Mixed source formats supported (WAV, MP3)

Audio file organization:

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

🤝 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

NeoDev
DATlib
DATimage
NGFX SoundBuilder
Raine
Mame
CHDMAN
Doxygen
MSYS2
Mkisofs
GCC
mpg123
ffmpeg
NSIS

📝 Changelog

Complete version history and changes documentation.

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

ResistanceVault/neocore

Folders and files

Latest commit

History

Repository files navigation