Quickstart Guide

This guide will help you set up the development environment, build Una Aventura Inesperada from source, and run it on an emulator or real Nintendo DS hardware.

Prerequisites

Before you begin, ensure you have the following:

DevkitPro ARM Toolchain

The DevkitPro ARM toolchain is required to compile Nintendo DS homebrew applications.Supported Platforms:

Windows (via MSYS2)
macOS (via Homebrew or pacman)
Linux (via pacman)

DevkitPro provides pre-built packages for all major operating systems. Visit devkitpro.org for platform-specific installation instructions.

System Requirements

Disk Space: ~500 MB for DevkitPro + toolchain
RAM: 2 GB minimum
OS: Windows 7+, macOS 10.13+, or Linux (kernel 3.2+)

Optional: NDS Emulator

For testing without hardware:

DeSmuME: Recommended for accuracy
melonDS: Modern alternative with improved features
NO$GBA: Lightweight debugger option

Optional: Flash Cart (for Real Hardware)

To run on actual Nintendo DS hardware:

R4 card
Acekard 2i
DSTWO
Any compatible flashcart with microSD support

Installation

Installing DevkitPro ARM

Follow the instructions for your operating system:

# Download and run the DevkitPro installer from:
# https://github.com/devkitPro/installer/releases

# After installation, open MSYS2 and install devkitARM:
pacman -S nds-dev

# Verify installation:
which arm-none-eabi-gcc
# Should output: /opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc

Verify Installation

Confirm DevkitPro ARM is correctly installed:

# Check compiler version
arm-none-eabi-gcc --version

# Verify environment variables
echo $DEVKITPRO
echo $DEVKITARM

# Check for libnds
ls $DEVKITPRO/libnds

Expected output:

arm-none-eabi-gcc (devkitARM release XX) X.X.X
/opt/devkitpro
/opt/devkitpro/devkitARM
include/  lib/

Building the Game

Clone or Download Source Code

Obtain the Una Aventura Inesperada source code:

git clone https://github.com/GomezJuanJose/UnaAventuraInesperada.git
cd UnaAventuraInesperada

Or extract from an archive if you downloaded a ZIP file.

Navigate to Source Directory

Navigate to the source directory:

cd source
ls

You should see:

main.c - Main game logic
teselas.h - Tile and level definitions
Various .h files for graphics assets
Makefile (if present)

Compile the Game

If a Makefile exists:

make clean
make

If no Makefile is present, compile manually:

# Compile the source
arm-none-eabi-gcc \
  -g -Wall -O2 \
  -march=armv5te -mtune=arm946e-s \
  -fomit-frame-pointer -ffast-math \
  -mthumb -mthumb-interwork \
  -I$DEVKITPRO/libnds/include \
  -DARM9 \
  -c main.c -o main.o

# Link the executable
arm-none-eabi-gcc \
  -g -mthumb -mthumb-interwork \
  -specs=ds_arm9.specs \
  main.o \
  -L$DEVKITPRO/libnds/lib \
  -lnds9 \
  -o una-aventura-inesperada.elf

# Convert to NDS ROM
ndstool -c una-aventura-inesperada.nds \
  -9 una-aventura-inesperada.elf \
  -b $DEVKITPRO/libnds/icon.bmp \
  "Una Aventura Inesperada;by Juan Jose Gomez Simon;Puzzle Game"

The build process should complete without errors. If you encounter issues, verify that all environment variables are set correctly.

Verify Build Output

Check that the ROM file was created:

ls -lh *.nds

Expected output:

-rw-r--r-- 1 user user 256K una-aventura-inesperada.nds

Running on Emulator

Test your build using an NDS emulator:

DeSmuME
melonDS
NO$GBA

DeSmuME (Recommended)

Installation:

# Windows: Download from https://desmume.org/download/
# macOS:
brew install --cask desmume
# Linux:
sudo apt install desmume  # Debian/Ubuntu

Running the Game:

# Command line
desmume una-aventura-inesperada.nds

# Or use File > Open ROM in the GUI

Controls:

Arrow Keys: D-Pad movement
Z/X/A/S: A/B/X/Y buttons
Q/W: L/R triggers
Mouse: Touchscreen (click and drag)
Enter: Start button

melonDS

Installation:

# Download from https://melonds.kuribo64.net/downloads.php

# Linux:
sudo apt install melonds

First Time Setup:

Launch melonDS
Go to Config > Emu settings
Set up BIOS files (optional for homebrew)

Running the Game:

melonDS una-aventura-inesperada.nds

Touchscreen: Click on the bottom screen to interact with menus and dialogs

NO$GBA (Debugger)

Installation:

Download from https://problemkaputt.de/gba.htm
Windows only

Running the Game:

NO$GBA.exe una-aventura-inesperada.nds

Debug Features:

Real-time memory viewer
CPU register inspection
Breakpoint support

Some emulators may have compatibility issues with touchscreen input or timer-based animations. DeSmuME and melonDS are recommended for the best experience.

Running on Real Hardware

Prepare Flash Cartridge

Insert a microSD card into your computer
Format as FAT32 if needed
Copy una-aventura-inesperada.nds to the root or games folder

Install on Nintendo DS

Safely eject the microSD from your computer
Insert microSD into your flash cartridge
Insert flash cartridge into Nintendo DS
Power on the DS

Launch the Game

Navigate to your flash cart’s menu
Select “una-aventura-inesperada.nds”
Press A to launch

The game should boot immediately and display the title screen on the top display.

First Playthrough Tips

Understanding the Controls

D-Pad Movement:

The player character moves in 2×2 tile blocks
Each direction moves exactly 2 tiles
Movement is grid-locked (no diagonal movement)

Movement System

// Each movement consumes 1 stamina point
// Grid movement is in 2-tile increments
if (movimientosJ ugador > 0 && posJugFila > 0) {
    posJugFila -= 2;  // Move up by 2 tiles
    movimientosJugador--;  // Consume stamina
    ActualizarBarraMovimientos();
}

Touchscreen Controls:

Tap menu buttons to navigate
Select quiz answers by tapping on the bottom screen
Use the restart button if you get stuck

Game Mechanics

Box Pushing

Push boxes by walking into them
Boxes move 2 tiles in the push direction
Boxes cannot be pushed into walls or other boxes
Use boxes to block enemies or create paths

Box Movement Logic

void MoverObstaculo(int direccion){
    // Check if space ahead is clear
    if(direccion == 0 && 
       mapMemory[(posJugFila-4)*32+posJugColumna] != 18 && 
       mapMemory[(posJugFila-4)*32+posJugColumna] != 19) {
        // Move box 2 tiles up
        mapMemory[(posJugFila-4)*32+posJugColumna] = 19;
        // Clear old position
        mapMemory[(posJugFila-2)*32+posJugColumna] = 3;
    }
}

Enemy Encounters

Enemies occupy 2×2 tiles like the player
Push enemies to move them or eliminate them
If an enemy has nowhere to go, it is eliminated
Eliminating an enemy costs 1 stamina (you don’t move)

Strategy: Use walls and boxes to trap enemies before pushing them.

Stamina Management

Each level has a specific movement limit
Watch the green stamina bar on the bottom screen
Plan your route carefully to avoid running out
Restarting the level refills stamina completely

Level Budgets:

Level 1: 18 moves
Level 2: 19 moves
Level 3: 23 moves
Level 4: 21 moves
Level 5: 24 moves

Quiz Questions

Answer questions correctly to advance
Wrong answers restart the current level
Each level has 1-3 questions
Touch the correct answer button quickly

The quiz questions are in Spanish. Make sure you understand the questions before selecting an answer.

Level 1 Walkthrough

Here’s a basic strategy for completing the first level:

Initial Assessment

Starting position: Bottom-left area
Movement budget: 18 moves
Obstacles: 2 enemies, 3 boxes
Goal: Reach the NPC at the top-right

Enemy Handling

Push the first enemy up and right to eliminate it against the wall:

Move right (1 move)
Move up (1 move)
Push enemy up (1 move)

Navigate Boxes

Clear a path by pushing boxes:

Push middle box right (1 move + movement)
Navigate around remaining boxes

Reach the Goal

Move to the NPC position and touch the goal tile (marked as tile 23):

// When player reaches goal
case 23: 
    ConsultarSistemaDialogo(); 
    return 6;

Answer Quiz

Three questions will appear:

Question 1: Select option 2 (right button)
Question 2: Select option 1 (left button)
Question 3: Select option 1 (left button)

Troubleshooting

Build Issues

'arm-none-eabi-gcc' not found

Problem: DevkitPro ARM is not in PATHSolution:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export DEVKITPRO=/opt/devkitpro
export DEVKITARM=$DEVKITPRO/devkitARM
export PATH=$DEVKITARM/bin:$PATH

# Reload shell
source ~/.bashrc

'nds.h' not found

Problem: libnds is not installed or not foundSolution:

# Reinstall libnds
sudo dkp-pacman -S libnds

# Verify installation
ls $DEVKITPRO/libnds/include/nds.h

Linking errors

Problem: Missing library filesSolution:

# Ensure libnds9 is available
ls $DEVKITPRO/libnds/lib/libnds9.a

# Add explicit library path
-L$DEVKITPRO/libnds/lib -lnds9

ndstool: command not found

Problem: NDS tools not installedSolution:

# Install complete NDS toolchain
sudo dkp-pacman -S nds-dev

# Verify ndstool
which ndstool

Runtime Issues

White screens on emulator

Problem: Graphics not loadingPossible causes:

Corrupted ROM build
Missing graphics assets in compilation
Emulator compatibility issue

Solution:

Rebuild the ROM: make clean && make
Try a different emulator
Verify all .h asset files are present

Touchscreen not responding

Problem: Can’t interact with menusSolution:

DeSmuME: Ensure mouse emulation is enabled (View > Touch Screen)
melonDS: Click directly on bottom screen area
Real DS: Recalibrate touchscreen in DS system settings

Game freezes during level transition

Problem: Hangs when answering questionsPossible cause: Timer interrupt issuesSolution:

Use accurate emulator settings (DeSmuME: Config > Emulation Settings > Use dynamic recompiler)
Rebuild ROM with optimizations: -O2 flag

Stamina bar not updating

Problem: Visual glitch with HUDCause: Framebuffer not refreshingSolution:

Check that ActualizarBarraMovimientos() is called after each move
Verify VRAM is properly initialized:

VRAM_A_CR = VRAM_ENABLE | VRAM_A_LCD;
fb = VRAM_A;

Flash Cart Issues

ROM not appearing in menu

Game crashes on real hardware

Problem: Works in emulator but not on DSPossible causes:

Flash cart firmware needs update
ROM header issues
Timing differences between emulator and hardware

Solution:

Update flash cart firmware
Rebuild with hardware-specific optimizations
Test on emulator with accurate settings first

Next Steps

Now that you have the game running:

Game Mechanics

Learn advanced strategies and game mechanics

Level Solutions

View optimal solutions for each puzzle level

Modding Guide

Create custom levels and modify graphics

Source Code Deep Dive

Understand the technical implementation

If you encounter issues not covered in this guide, check the DevkitPro documentation at devkitpro.org or the libnds API reference.

Getting Started

Game Design

Development

Technical Reference

Quickstart

Quickstart Guide

Prerequisites

Installation

Installing DevkitPro ARM

Verify Installation

Building the Game

Running on Emulator

DeSmuME (Recommended)

melonDS

NO$GBA (Debugger)

Running on Real Hardware

First Playthrough Tips

Understanding the Controls

Game Mechanics

Level 1 Walkthrough

Troubleshooting

Build Issues

Runtime Issues

Flash Cart Issues

Next Steps

Game Mechanics

Level Solutions

Modding Guide

Source Code Deep Dive

Build docs developers (and LLMs) love

Getting Started

Game Design

Development

Technical Reference

​Quickstart Guide

​Prerequisites

​Installation

​Installing DevkitPro ARM

​Verify Installation

​Building the Game

​Running on Emulator

​DeSmuME (Recommended)

​melonDS

​NO$GBA (Debugger)

​Running on Real Hardware

​First Playthrough Tips

​Understanding the Controls

​Game Mechanics

​Level 1 Walkthrough

​Troubleshooting

​Build Issues

​Runtime Issues

​Flash Cart Issues

​Next Steps

Game Mechanics

Level Solutions

Modding Guide

Source Code Deep Dive

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Installation

Installing DevkitPro ARM

Verify Installation

Building the Game

Running on Emulator

DeSmuME (Recommended)

melonDS

NO$GBA (Debugger)

Running on Real Hardware

First Playthrough Tips

Understanding the Controls

Game Mechanics

Level 1 Walkthrough

Troubleshooting

Build Issues

Runtime Issues

Flash Cart Issues

Next Steps