Difference between revisions of "Nintendo 3DS"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Initial version)
 
m
(8 intermediate revisions by 3 users not shown)
Line 13: Line 13:
buildbot=yes|
buildbot=yes|
firstversion=2.1.1|
firstversion=2.1.1|
maintainer=[[User:BgK|bgK]]|
maintainer=[[User:phcoder|phcoder]]|
packager=[[User:BgK|bgK]]|
packager=[[User:phcoder|phcoder]]|
pkgend=-3ds.zip|
pkgend=-3ds.zip|
icon=3ds|
icon=3ds|
forum=10|
forum=13|
notes=|
notes=|


Line 44: Line 44:
}}
}}


== Installation ==
== About ==
There are two possible formats to be used: 3DSX and CIA.
ScummVM has been ported to the Nintendo 3DS.  
The 3DSX format is considered more ethical because it does not make use of
invalid title IDs, which get logged. It is also compatible with homebrew loading
methods that do not involve CFW.
The 3DSX format is exclusively used by the Homebrew Launcher and its derivatives.
The CIA format can be installed directly to the 3DS home menu and can be launched
using any CFW (Custom Firmware) of your choice.


Installing the Homebrew Launcher or any CFW is beyond the scope of this page.
For more information, including how to install and use ScummVM, see the [https://docs.scummvm.org/en/latest/other_platforms/nintendo_3ds.html Nintendo 3DS user documentation].


=== 3DSX installation ===
== Developer information ==
You need to merely extract the ScummVM 3DSX files to your SD card so that all
files reside in the <code>/3ds/scummvm/</code> directory. It can then be launched by Homebrew Launcher
or a similar implementation.


=== CIA installation ===
=== Compiling ScummVM  ===
The CIA format requires a DSP binary dump saved on your SD card as <code>/3ds/dspfirm.cdc</code>
==== Prerequisites ====
for proper audio support. You can search online to find software to dump this.
Not having this file will cause many problems with games that need audio, sometimes
even crashing, so this is NOT considered optional.
 
Using any CIA installation software (search elsewhere for that), you need to install
the <code>scummvm.cia</code> file.
 
== Controls ==
=== Default key mappings ===
 
The key mappings can be customized in the options dialog for the global mappings,
and in the edit game dialog for per-game mappings. Per-game mappings overlay the
global mappings, so if a button is bound to an action twice, the per-game mapping
wins.
 
The default keymap is:
{{3DSControls}}
 
=== Hover mode ===
When you use the touchscreen, you are simulating the mere moving of the mouse. You
can click only with taps, meaning it is impossible to drag stuff or hold down a
mouse button without using buttons mapped to right/left-click.
 
=== Drag mode ===
Every time you touch and release the touchscreen, you are simulating the click and
release of the mouse buttons. At the moment, this is only a left-click.
 
=== Magnify mode ===
Due to the low resolutions of the 3DS's two screens (400x240 for the top, and 320x240
for the bottom), games that run at a higher resolution will inevitably lose some visual
detail from being scaled down. This can result in situations where essential information
is undiscernable, such as text. Magnify mode increases the scale factor of the top screen
back to 1; the bottom screen remains unchanged. The touchscreen can then be used to change
which part of the game display is being magnified. This can all be done even in situations
where the cursor is disabled, such as during full-motion video (FMV) segments.
 
When activating magnify mode, touchscreen controls are automatically switched to hover
mode; this is to reduce the risk of the user accidentally inputting a click when changing
the magnified area via dragging the stylus. Clicking can still be done at will as in normal
hover mode. Turning off magnify mode will revert controls back to what was being used
previously (ex: if drag mode was in use prior to activating magnify mode, drag mode will
be reactivated upon exiting magnify mode), as well as restore the top screen's previous
scale factor.
 
Currently magnify mode can only be used when the following conditions are met:
* In the 3DS config menu, "Use Screen" is set to "Both"
* A game is currently being played
* The horizontal and/or vertical resolution in-game is greater than that of the top screen
 
Magnify mode cannot be used in the Launcher menu.
 
== Supported Games ==
While all the games should run on the 3DS (report if they do not), there are
many games which are unplayable due to the lack of CPU speed on the 3DS. So if
you play any games that run really slow, this is not considered a bug, but rather
a hardware limitation.
 
The New 3DS console has much better performance, but there are still many newer and
high-resolution games that cannot be played. A list of these unplayable games and
game engines will eventually be listed here.
 
== Compiling ==
=== Prerequisites ===
* Latest version of devkitPro, which comes with devkitARM and <code>libctru</code>
* Latest version of devkitPro, which comes with devkitARM and <code>libctru</code>
* <code>citro3d</code> thorugh devkitPro's pacman
* <code>citro3d</code> thorugh devkitPro's pacman
* Optional: You should compile third-party libraries for the 3ds (commonly referred to as portlibs in the devkitPRO community). Some games requires these to operate properly.
* Optional: You should compile third-party libraries for the 3ds (commonly referred to as portlibs in the devkitPRO community). Some games requires these to operate properly.


=== Compiling third-party libraries ===
==== Compiling third-party libraries ====
It is strongly recommended that you use devkitPro's pacman in order to get the most recent
It is strongly recommended that you use devkitPro's pacman in order to get the most recent
portlibs for your build.
portlibs for your build.
Line 136: Line 64:


{|class="wikitable"
{|class="wikitable"
!  Library      ||  Package            
!  Library      ||  Package
|-
|  zlib        ||  3ds-zlib
|-
|-
zlib        ||  3ds-zlib           
libpng      ||  3ds-libpng
|-
|-
libpng      ||  3ds-libpng         
libjpeg      ||  3ds-libjpeg-turbo
|-
|-
libjpeg      ||  3ds-libjpeg-turbo   
freetype2    ||  3ds-freetype
|-
|-
freetype2    ||  3ds-freetype       
libmad      ||  3ds-libmad
|-
|-
libmad       ||  3ds-libmad         
libogg       ||  3ds-libogg
|-
|-
libogg       ||  3ds-libogg         
tremor       ||  3ds-libvorbisidec
|-
|-
tremor      ||  3ds-libvorbisidec   
flac        ||  3ds-flac
|-
|-
flac        ||  3ds-flac           
libtheora    ||  3ds-libtheora
|-
|-
|  curl        ||  3ds-curl            
|  curl        ||  3ds-curl
|}
|}


Line 187: Line 117:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkdir -p $PORTLIBS
mkdir -p $PORTLIBS_PREFIX
./configure --prefix=$PORTLIBS --host=arm-none-eabi --disable-shared --enable-static
./configure --prefix=$PORTLIBS_PREFIX --host=arm-none-eabi --disable-shared --enable-static
make
make
make install
make install
Line 195: Line 125:
Most libraries used can be compiled with same commands and configuration flags.
Most libraries used can be compiled with same commands and configuration flags.


=== Manually setting up the environment ===
==== Manually setting up the environment ====
In case you don't have the helpers package downloaded, you can use the following to set-up
In case you don't have the helpers package downloaded, you can use the following to set-up
your environment variables.
your environment variables.
Line 210: Line 140:
In the source directory of the library:
In the source directory of the library:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
export PORTLIBS=$DEVKITPRO/portlibs/3ds
export PORTLIBS_PREFIX=$DEVKITPRO/portlibs/3ds
export PATH=$DEVKITARM/bin:$PATH
export PATH=$DEVKITARM/bin:$PATH
export PKG_CONFIG_PATH=$PORTLIBS/lib/pkgconfig
export PKG_CONFIG_PATH=$PORTLIBS_PREFIX/lib/pkgconfig
export PKG_CONFIG_LIBDIR=$PORTLIBS/lib/pkgconfig
export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig
export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2
export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2
                     -mword-relocations -ffunction-sections -fdata-sections"
                     -mword-relocations -ffunction-sections -fdata-sections"
export CPPFLAGS="-I$PORTLIBS/include -I$CTRULIB/include"
export CPPFLAGS="-I$PORTLIBS_PREFIX/include -I$CTRULIB/include"
export LDFLAGS="-L$PORTLIBS/lib"
export LDFLAGS="-L$PORTLIBS_PREFIX/lib"
</syntaxhighlight>
</syntaxhighlight>


== Compiling ScummVM ==
==== Compiling ScummVM ====
Do the following in a fresh terminal.
Do the following in a fresh terminal.


Line 226: Line 156:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
export PATH=$DEVKITARM/bin:$PATH
export PATH=$DEVKITARM/bin:$PATH
</syntaxhighlight>
In case you get an error about "namespace _3DS", edit the line in /opt/devkitpro/3dsvars.sh that reads
<syntaxhighlight lang="bash">
export CPPFLAGS="-D_3DS -I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"
</syntaxhighlight>
and remove the "-D_3DS" part so that it reads
<syntaxhighlight lang="bash">
export CPPFLAGS="-I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"
</syntaxhighlight>
</syntaxhighlight>


Note: In more recent codebases of ScummVM, you may or may not need to set the following beforehand:
Note: In more recent codebases of ScummVM, you may or may not need to set the following beforehand:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
export PKG_CONFIG_LIBDIR=$PORTLIBS/lib/pkgconfig
export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig
</syntaxhighlight>
</syntaxhighlight>
See above for <code>$PORTLIBS</code>.
See above for <code>$PORTLIBS_PREFIX</code>.


ScummVM doesn't provide the CA certificates bundle required by the cloud synchronization features.
ScummVM doesn't provide the CA certificates bundle required by the cloud synchronization features.
Line 262: Line 201:
Note: using dynamic plugins as suggested is required when building with most or all of the
Note: using dynamic plugins as suggested is required when building with most or all of the
game engines enabled in order to keep the memory usage low and avoid stability issues.
game engines enabled in order to keep the memory usage low and avoid stability issues.
=== Debugging ScummVM ===
''This section is based on information from [https://bugs.scummvm.org/ticket/11292#comment:4 Trac #11292].''
When reporting crashes to the issue tracker, it is recommended that you capture a backtrace of the crash? It's a bit of a convoluted process but it's not possible to do much without it. It's described here if you are not familiar:
* Create a build of ScummVM using "./configure --host=3ds --disable-all-engines --enable-engines=scumm_7_8,he,sci32 --enable-all-engines --enable-debug"
* Get devkitARM from here: ​https://devkitpro.org/wiki/Getting_Started. You don't need to get the whole thing working, just the GDB debugger.
* Start ScummVM on your 3DS, go to the Rosalina menu (L+Down+Select), enable the debugger (Debugger options > enable debugger), go to the process list and select ScummVM (3dsx_app if you used the homebrew launcher). Take note of the IP address of your 3DS and the debugger port. They are displayed in the menu. For example, it might look like 192.168.1.87:4000. Close the Rosalina menu. If it closes ScummVM, try again, but open a dialog in ScummVM before opening the Rosalina menu (The keypress to close Rosalina is sometimes passed to ScummVM).
* On your computer in the devkitARM shell, run "arm-none-eabi-gdb /path/to/scummvm.elf" (with the location where you downloaded that file). Then, in GDB, enter "target remote 192.168.1.87:4000" (with your IP and port) to connect to the 3DS. Enter 'c' to resume execution.
* On the 3DS, reproduce the crash.
* On the computer, GDB should have trapped the error. Enter "thread apply all bt" to print a backtrace.
Please copy the backtrace into the ticket as well as other warnings or messages you may see in the debugger output.
In case you don't succeed in capturing a backtrace, please attach the crash dump from the Luma error screen (they are saved on the SD card in /luma/dumps).
It's also recommended that you attach a copy of the log file, which can be found at "sdmc:/3ds/scummvm/scummvm.log".

Revision as of 21:12, 26 February 2023

3ds.png Nintendo 3DS Port
Latest Released Version 2.8.1
Supported Audio Options MP3, OGG, FLAC, Uncompressed
Additional Webpage(s) None
Maintainer(s) phcoder
Packager(s) phcoder
Forum Port Forum
Status Maintained
First Official Version 2.1.1

About

ScummVM has been ported to the Nintendo 3DS.

For more information, including how to install and use ScummVM, see the Nintendo 3DS user documentation.

Developer information

Compiling ScummVM

Prerequisites

  • Latest version of devkitPro, which comes with devkitARM and libctru
  • citro3d thorugh devkitPro's pacman
  • Optional: You should compile third-party libraries for the 3ds (commonly referred to as portlibs in the devkitPRO community). Some games requires these to operate properly.

Compiling third-party libraries

It is strongly recommended that you use devkitPro's pacman in order to get the most recent portlibs for your build.

The following libraries can be downloaded with pacman:

Library Package
zlib 3ds-zlib
libpng 3ds-libpng
libjpeg 3ds-libjpeg-turbo
freetype2 3ds-freetype
libmad 3ds-libmad
libogg 3ds-libogg
tremor 3ds-libvorbisidec
flac 3ds-flac
libtheora 3ds-libtheora
curl 3ds-curl

At the moment of writing, the version of freetype2 packaged by devkitPro has an issue where it allocates too much data on the stack when ScummVM loads GUI themes. As a workaround, an older version can be used. Version 2.6.5 is known to work well. The instructions below can be used to compile it.

At the moment of writing, faad is not in the devkitPro 3DS pacman repository. It can be compiled by following the instructions in the section below, in case it cannot be found through pacman.

The following pacman packages are also recommended:

  • 3ds-dev
  • devkitpro-pkgbuild-helpers

Once you have the devkitpro-pkgbuild-helpers package, you should be able to find the following scripts in your /opt/devkitpro folder:

  • devkitarm.sh
  • 3dsvars.sh

Run them one after the other with `source` in order to setup your environment variables for cross-compiling:

source /opt/devkitpro/devkitarm.sh
source /opt/devkitpro/3dsvars.sh

After that, you can download the libraries you want to cross compile, run any autoconf scripts that they may have, and then they can usually be built with the following steps from their source directory:

mkdir -p $PORTLIBS_PREFIX
./configure --prefix=$PORTLIBS_PREFIX --host=arm-none-eabi --disable-shared --enable-static
make
make install

Most libraries used can be compiled with same commands and configuration flags.

Manually setting up the environment

In case you don't have the helpers package downloaded, you can use the following to set-up your environment variables.

It is assumed that you have these variables already set up. If not, then do so:

DEVKITPRO Your root devkitPro directory
DEVKITARM Your root devkitARM directory (probably same as $DEVKITPRO/devkitARM)
CTRULIB Your root libctru directory (probably same as $DEVKITPRO/libctru)

In the source directory of the library:

export PORTLIBS_PREFIX=$DEVKITPRO/portlibs/3ds
export PATH=$DEVKITARM/bin:$PATH
export PKG_CONFIG_PATH=$PORTLIBS_PREFIX/lib/pkgconfig
export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig
export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2
                    -mword-relocations -ffunction-sections -fdata-sections"
export CPPFLAGS="-I$PORTLIBS_PREFIX/include -I$CTRULIB/include"
export LDFLAGS="-L$PORTLIBS_PREFIX/lib"

Compiling ScummVM

Do the following in a fresh terminal.

In case you get a "compiler not found" message, add the toolchain's executables to your PATH:

export PATH=$DEVKITARM/bin:$PATH

In case you get an error about "namespace _3DS", edit the line in /opt/devkitpro/3dsvars.sh that reads

export CPPFLAGS="-D_3DS -I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"

and remove the "-D_3DS" part so that it reads

export CPPFLAGS="-I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"

Note: In more recent codebases of ScummVM, you may or may not need to set the following beforehand:

export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig

See above for $PORTLIBS_PREFIX.

ScummVM doesn't provide the CA certificates bundle required by the cloud synchronization features. You need to download it from the curl website: https://curl.haxx.se/ca/cacert.pem, and instruct the build system to package it in the binary:

export DIST_3DS_EXTRA_FILES=/path/to/cacert.pem

The name of the file must be cacert.pem.

From the root of the scummvm repository:

./configure --host=3ds --enable-plugins --default-dynamic
make

Additionally compile to specific formats to be used on the 3DS:

make scummvm.3dsx
make scummvm.cia

Assuming everything was successful, you'll be able to find the binary files in the root of your scummvm folder.

Note: for the CIA format, you will need the makerom and bannertool tools which are not supplied with devkitPro.

Note: using dynamic plugins as suggested is required when building with most or all of the game engines enabled in order to keep the memory usage low and avoid stability issues.

Debugging ScummVM

This section is based on information from Trac #11292.

When reporting crashes to the issue tracker, it is recommended that you capture a backtrace of the crash? It's a bit of a convoluted process but it's not possible to do much without it. It's described here if you are not familiar:

  • Create a build of ScummVM using "./configure --host=3ds --disable-all-engines --enable-engines=scumm_7_8,he,sci32 --enable-all-engines --enable-debug"
  • Get devkitARM from here: ​https://devkitpro.org/wiki/Getting_Started. You don't need to get the whole thing working, just the GDB debugger.
  • Start ScummVM on your 3DS, go to the Rosalina menu (L+Down+Select), enable the debugger (Debugger options > enable debugger), go to the process list and select ScummVM (3dsx_app if you used the homebrew launcher). Take note of the IP address of your 3DS and the debugger port. They are displayed in the menu. For example, it might look like 192.168.1.87:4000. Close the Rosalina menu. If it closes ScummVM, try again, but open a dialog in ScummVM before opening the Rosalina menu (The keypress to close Rosalina is sometimes passed to ScummVM).
  • On your computer in the devkitARM shell, run "arm-none-eabi-gdb /path/to/scummvm.elf" (with the location where you downloaded that file). Then, in GDB, enter "target remote 192.168.1.87:4000" (with your IP and port) to connect to the 3DS. Enter 'c' to resume execution.
  • On the 3DS, reproduce the crash.
  • On the computer, GDB should have trapped the error. Enter "thread apply all bt" to print a backtrace.

Please copy the backtrace into the ticket as well as other warnings or messages you may see in the debugger output.

In case you don't succeed in capturing a backtrace, please attach the crash dump from the Luma error screen (they are saved on the SD card in /luma/dumps).

It's also recommended that you attach a copy of the log file, which can be found at "sdmc:/3ds/scummvm/scummvm.log".