diff options
| -rw-r--r-- | backends/platform/3ds/README | 185 | ||||
| -rw-r--r-- | backends/platform/3ds/README.md | 230 |
2 files changed, 230 insertions, 185 deletions
diff --git a/backends/platform/3ds/README b/backends/platform/3ds/README deleted file mode 100644 index 516e694f64..0000000000 --- a/backends/platform/3ds/README +++ /dev/null @@ -1,185 +0,0 @@ -ScummVM 3DS README ------------------------------------------------------------------------- - -Table of Contents: ------------------- -1.0) Installation - * 1.1 3DSX installation - * 1.2 CIA installation -2.0) Controls - * 2.1 Default key mappings - * 2.2 Hover mode - * 2.3 Drag mode -3.0) Supported Games -4.0) Compiling - * 4.1 Prerequisites - * * 4.1.1 Compiling third-party libraries - * 4.2 Compiling ScummVM - * 4.3 Warning for 3DSX build - - - -1.0) Installation ------------------ -There are two possible formats to be used: 3DSX and CIA (recommended). -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 README. -Look elsewhere to see how to install those if you do not already have them set up. - - -1.1) 3DSX installation ----------------- -The CIA format is recommended for stability and maximum game support. If that is -not an option, you will need one of a collection of 3DS titles installed on your -system in order to properly launch ScummVM as a 3DSX. This is because the -Homebrew Launcher hijacks other processes to run 3DSX homebrew, and ScummVM is a -particularly large homebrew that can't be launched with the resources provided -by standard system applications. - -You will need one of the following (installed or physically in cart slot): - -- Youtube -- Monster Hunter 4 Ultimate Special Demo -- Monster Hunter 4 Ultimate -- Monster Hunter 4G -- Super Smash Bros. for Nintendo 3DS Demo -- Super Smash Bros. for Nintendo 3DS Special Demo -- Super Smash Bros. for Nintendo 3DS - -Once you have one of the above, you need to merely extract all ScummVM 3DS files -to the root of your SD card so that all files reside in the /3ds/scummvm/ directory. - - -1.2) CIA installation ---------------------- -The CIA format requires a DSP binary dump saved on your SD card as /3ds/dspfirm.cdc -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 scummvm.cia file. Then, just like what is done with the 3DSX installation, you -need to extract all ScummVM 3DS files (scummvm.cia excluded) to the root of your SD -card so that all files reside in the /3ds/scummvm/ directory. - - - -2.0) Controls -------------- - -2.1) Default key mappings -------------------------- -The D-Pad and A/B/X/Y buttons have mirrored usage. So they do the same things -depending on if you're right or left-handed. - -| Buttons | Function | -|------------|--------------------------------| -| A / D-left | Left-click | -| X / D-up | Right-click | -| B / D-down | ESC (skips cutscenes and such) | -| L | Use virtual keyboard | -| R | Toggle hover/drag modes | -| Start | Open game menu | -| Select | Open 3DS config menu | -| Circle Pad | Move the cursor | - - -2.2) 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. - - -2.3) 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. - - - -3.0) Supported Games --------------------- -The full game engine compatibility list can be found here: -http://scummvm.org/compatibility/ - -While all the above 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. Though possible GPU optimizations are always in the works. -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. - - - -4.0) Compiling --------------- - -4.1) Prerequisites ------------------- - - devkitARM (presumably with libctru, picasso and such) - - citro3d - - 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. - - -4.1.1) Compiling third-party libraries --------------------------------------- -Most libraries used can be compiled with same commands and configuration flags. - -It is assumed that you have these environment variables defined: - - 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=$DEVKITPRO/portlibs/armv6k - - $ export PATH=$DEVKITARM/bin:$PATH - - $ export PKG_CONFIG_PATH=$PORTLIBS/lib/pkgconfig - - $ export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2 - -mword-relocations -ffunction-sections -fdata-sections" - - $ export CPPFLAGS="-I$PORTLIBS/include -I$CTRULIB/include" - - $ export LDFLAGS="-L$PORTLIBS/lib" - - $ mkdir -p $PORTLIBS - - $ ./configure --prefix=$PORTLIBS --host=arm-none-eabi --disable-shared - --enable-static - - $ make - - $ make install - -Useful libraries (and special config flags needed): - - zlib - - libpng - - libjpeg - - freetype2 --without-bzip2 --without-harfbuzz - - libmad - - tremor - - flac --disable-cpplibs --without-flac - - faad - - -4.2) Compiling ScummVM ----------------------- - - $ ./configure --host=3ds - - $ make - -Additionally compile to specific formats to be used on the 3ds: - - $ make scummvm.3dsx - - $ make scummvm.cia - - -4.3) Warning for 3DSX build ---------------------------- -The above configuration command will include all game engines by default and will -likely be too massive to run using the 3DSX format. Until dynamic modules are figured -out, you should configure engines like this for 3DSX builds: - - - $ ./configure --host=3ds --disable-all-engines--enable-engine=scumm-7-8,myst,riven, - sword1,sword2,sword25,sci,lure,sky,agi,agos - -Choose whatever engines you want, but if the ELF's .text section exceeds ~10MB, it -won't be playable unless it's a CIA. diff --git a/backends/platform/3ds/README.md b/backends/platform/3ds/README.md new file mode 100644 index 0000000000..a17fc6a98e --- /dev/null +++ b/backends/platform/3ds/README.md @@ -0,0 +1,230 @@ +ScummVM 3DS README +------------------------------------------------------------------------ + +Table of Contents: +------------------ +1.0) Installation + * 1.1 3DSX installation + * 1.2 CIA installation + * 1.3 Additional files + +2.0) Controls + * 2.1 Default key mappings + * 2.2 Hover mode + * 2.3 Drag mode + +3.0) Supported Games + +4.0) Compiling + * 4.1 Prerequisites + * * 4.1.1 Compiling third-party libraries + * * 4.1.2 Manually setting up the environment + * * 4.1.3 Note on FLAC + * 4.2 Compiling ScummVM + * 4.3 Warning for build sizes + +1.0) Installation +----------------- +There are two possible formats to be used: 3DSX and CIA. +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 README. + +1.1) 3DSX installation +---------------- +You need to merely extract the ScummVM 3DSX files to your SD card so that all +files reside in the `/3ds/scummvm/` directory. It can then be launched by Homebrew Launcher +or a similar implementation. + +1.2) CIA installation +--------------------- +The CIA format requires a DSP binary dump saved on your SD card as `/3ds/dspfirm.cdc` +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 `scummvm.cia` file. Then, just like what is done with the 3DSX installation, you +need to extract all ScummVM 3DS files (`scummvm.cia` excluded) to the root of your SD +card so that all files reside in the `/3ds/scummvm/` directory. + +1.3) Additional files +--------------------- +In order to use the Virtual Keyboard, you need to get the: +`backends/vkeybd/packs/vkeybd_zmall.zip` file from ScummVM's repository, and +place it on your SD card, in the `/3ds/scummvm/kb` folder. + +In case you want a translated GUI, you need to get the: +`scummvm/gui/themes/translations.dat` file from ScummVM's repository, and place +it on your SD card, in the `/3ds/scummvm/themes` folder. + +2.0) Controls +------------- + +2.1) Default key mappings +------------------------- +The D-Pad and A/B/X/Y buttons have mirrored usage. So they do the same things +depending on if you're right or left-handed. + +| Buttons | Function | +|------------|--------------------------------| +| A / D-left | Left-click | +| X / D-up | Right-click | +| B / D-down | ESC (skips cutscenes and such) | +| L | Use virtual keyboard | +| R | Toggle hover/drag modes | +| Start | Open game menu | +| Select | Open 3DS config menu | +| Circle Pad | Move the cursor | + +2.2) 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. + +2.3) 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. + +3.0) Supported Games +-------------------- +The full game engine compatibility list can be found here: +http://scummvm.org/compatibility/ + +While all the above 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. Though possible GPU optimizations are always in the works. +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. + +4.0) Compiling +-------------- +4.1) 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. + + +4.1.1) 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-zlib | +| libjpeg | 3ds-libjpeg-turbo | +| freetype2 | 3ds-freetype | +| libmad | 3ds-libmad | +| libogg | 3ds-libogg | +| tremor | 3ds-libvorbisidec | + +At the moment of writing, `faad` and `flac` are not in the devkitPro 3DS pacman +repository. They can be compiled by following the instructions in the section below, +in case they 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` + +Execute them one after the other (`devkitarm.sh` should be executed first), in order +to setup your environment variables for cross-compiling. + +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 + $ ./configure --prefix=$PORTLIBS --host=arm-none-eabi --disable-shared \ + --enable-static + $ make + $ make install +``` +Most libraries used can be compiled with same commands and configuration flags. + +4.1.2) 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=$DEVKITPRO/portlibs/3ds + $ export PATH=$DEVKITARM/bin:$PATH + $ export PKG_CONFIG_PATH=$PORTLIBS/lib/pkgconfig + $ export PKG_CONFIG_LIBDIR=$PORTLIBS/lib/pkgconfig + $ export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2 + -mword-relocations -ffunction-sections -fdata-sections" + $ export CPPFLAGS="-I$PORTLIBS/include -I$CTRULIB/include" + $ export LDFLAGS="-L$PORTLIBS/lib" + ``` + +4.1.3) Note on FLAC: +-------------------- +At the moment of writing, the `libflac` library cannot be compiled for the 3DS out of the box. +However, the following patch (for the Nintendo Switch) can be adapted and applied to it: +https://github.com/devkitPro/pacman-packages/tree/master/switch/flac + +Afterwards, the library can be built with: +``` + $ CFLAGS="${CFLAGS} -D__3DS__ " \ + ./configure --prefix="${PORTLIBS_PREFIX}" --host=arm-none-eabi \ + --disable-shared --enable-static \ + --disable-xmms-plugin --disable-cpplibs \ + --disable-sse --without-ogg +``` + +4.2) Compiling ScummVM +---------------------- +From the root of the scummvm repository: +``` + $ ./configure --host=3ds + $ 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. + +4.3) Warning for build sizes +--------------------------- +The above configuration command will include all game engines by default and will +likely be too massive to run with stability using either the 3DSX or the CIA format. +Until dynamic modules are figured out, you should configure engines like this: +``` + $ ./configure --host=3ds --disable-all-engines--enable-engine=scumm-7-8,myst,riven, \ + sword1,sword2,sword25,sci,lure,sky,agi,agos +``` +Choose whatever engines you want, but if the ELF's .text section exceeds ~10MB-12MB, +you may experience crashes in memory-intensive games such as COMI, Broken Sword and Discworld 2. |