This covers all variants of SquirrelJME, for specific variant documentation please see:
Command Line Usage
The following may be used at the command line, the format is the same
as java. An option within square brackets [] are optional, and
any option within parenthesis () are required. The usage of SquirrelJME is
in the following format:
squirreljme [options]- Start into the launcher.
squirreljme [options] -jar a.jar- Directly launch the given Jar, bypassing the launcher.
squirreljme [options] mainClass [mainArgs|...]- Standard launch into the specific classpath and main arguments.
- For this option,
-classpath (class:path:...)may be used
squirreljme -XdebuggerOnly [options]- Only launch the built-in SquirrelJME debugger and not an actual virtual machine.
The available options are:
-Xclock:(infinite|0|1-2147483647)- Sets the number of Java instructions that can run per single clock cycle.
- This only applies to NanoCoat.
- The default is
infinite, or0, which means as many as possible. - Otherwise, only up to the given number of Java instructions will run per
thread loop on a given thread until
Thread.sleep(),Thread.yield(),Object.wait(), or other blocking action. - If used with
-Xthread:coopand-Xthread:shared, this will affect how many threads together can run in a single cycle. - Optimizations will affect how many instructions can run per second,
unless
-Xintis set. - If used with
-Xlp, this will significantly reduce power usage.
-Xclutter:(release|debug)- Use the given core libraries with the given clutter level.
releaseincludes obfuscation and no debugging and thus runs faster.debugdoes not have any obfuscation and may work in cases where obfuscation and optimization may cause issues.
-Xdebug[:fork|nofork]- Enable debugging but with the internal built-in SquirrelJME debugger and not a JDWP connection over TCP.
- This is supported under the
hostedemulator, however if you launch another application within it will not debug that process, therefor if you wish to debug you should use-jar. - Optionally,
forkornoforkcan be specified to where the internal debugger to launched as a separate process or not.
-XdebuggerOnly- Launches the built-in SquirrelJME Debugger, if available.
-Xemulator:(vm)- Specifies the backend emulator to use, the supported options are:
hosted-- Uses the host JVM to run all the software.springcoat-- SpringCoat, interpreter written in Java.nanocoat-- NanoCoat, interpreter written in C.
- Specifies the backend emulator to use, the supported options are:
-Xentry:id- Used with
-jar, this allows one to specify an entry point index, application name, or application entry point to determine which one to launch within the Jar as there may be multiple. - By default, if not specified, the first is always used.
- Used with
-Xint- Alias for
-Xemulator:springcoat.
- Alias for
-Xjdwp:[hostname]:port- Enable debugging.
- If
hostnameis specified then the debugger will connect to the remote host that is a listening JDWP debugger. - Otherwise, if only
portis specified then the debugger will wait and listen on the given port for an incoming connection.
-Xlibraries:(class:path:...)- Specifies libraries that should be available to the virtual machine
and the suite management system, note that this is not the same as
the
-classpathoption as that is for the current application. - Wildcard directories may be specified in the following way, depending
on the operating system and possible shell expansion:
/path/to/directory/*/path/to/directory/**/path/to/directory/*.*wildcard=/path/to/directory
- Specifies libraries that should be available to the virtual machine
and the suite management system, note that this is not the same as
the
-Xlp- Low power mode, rather than yielding the thread this will instead sleep for a short duration.
- This only applies to NanoCoat.
- This has significant performance considerations.
-Xrom:(path)- Specifies the SpringCoat ROM that should be used by the virtual machine.
-Xscritchui:(ui)- Rather than the default, use a specific user interface library.
- This may also be set by using
cc.squirreljme.scritchui. - Alternatively, the environment variable
SQUIRRELJME_SCRITCHUI_INTERFACEmay be used. nonedisables ScritchUI.
-Xsnapshot:(path-to-nps)- Profile the virtual machine and store the profile results into the given VisualVM snapshot file.
-XstartOnFirstThread- Ignored.
-Xthread:(single|coop|shared|multi|smt|noht)- Sets the threading mode of the virtual machine.
- This only applies to NanoCoat.
single/coop-- Single threaded using cooperative multitasking.shared-- Single threaded using virtualized preemptive multitasking.multi/smt-- Multi threaded using asynchronous multitasking.noht-- Same assmtwith hyper-threading disabled or affinity adjusted, if supported by the target system and CPU.
-Xtrace:option[,option[,...]]-- Trace optionsall-- Enable all.allocation-- Allocations such asnew.classInitialize-- Class is initialized.defaultPackage-- In default package only.ignoredException-- Exception that may be ignored.instructions-- Instructions being executed.invokeStatic-- Static invocations.notMainThread-- Do not trace on the main thread.methodEntry-- Entry of methods.methodExit-- Exit of methods.missingClass-- Class does not exist.mleCall-- SquirrelJME MLE Native Calls.monitorEnter-- Monitor is entered.monitorExit-- Exiting a monitor.monitorNotify-- Monitor is notified.monitorWait-- Monitor is waited on.threadNew-- New thread is created.vmException-- Virtual machine exceptions.
-Dsysprop=value- Defines the given system property.
-classpath (class:path:...)- Specifies the class path to use for the current application, the entries must be visible from the library path.
-jar (path.jar)- Launches the given Jar file.
-client- Ignored.
-server- Ignored.
-zero- Alias for
-Xemulator:springcoat.
- Alias for
Default Directories
SquirrelJME has a set of default directories, which have a priority order and may be overridden by environment variables.
<ENVIRONMENT_VARIABLE>-- value is read from an environment variable.[Another Type]-- value is read from another directory type.
Any entry with {~} means the first character will be placed by your home
directory, <HOME> on POSIX or <USERHOME> on Windows.
The following replacements are intended to be used in multi-arch setups. Note that the system and architectures must be of the names used by SquirrelJME.
{system}-- The name of the current system, all lowercase.{SYSTEM}-- Same as above, except all uppercase.
{arch}-- The name of the current architecture, all lowercase.{ARCH}-- Same as above, except all uppercase.
The directory types and their order of precedence are:
- Cache
<SQUIRRELJME_CACHE_HOME>{~}<LOCALAPPDATA>/squirreljme/cache(Windows)<APPDATA>/squirreljme/cache(Windows)<PROGRAMDATA>/squirreljme/cache(Windows)<XDG_CACHE_HOME>/squirreljme(POSIX)<HOME>/.cache/squirreljme(POSIX)
- Config
<SQUIRRELJME_CONFIG_HOME>{~}<APPDATA>/squirreljme/config(Windows)<PROGRAMDATA>/squirreljme/config(Windows)<XDG_CONFIG_HOME>/squirreljme(POSIX)<HOME>/.config/squirreljme(POSIX)
- Data
<SQUIRRELJME_DATA_HOME>{~}<APPDATA>/squirreljme/data(Windows)<PROGRAMDATA>/squirreljme/data(Windows)<XDG_DATA_HOME>/squirreljme(POSIX)<HOME>/.local/share/squirreljme(POSIX)
- State
<SQUIRRELJME_STATE_HOME>{~}<LOCALAPPDATA>/squirreljme/state(Windows)<APPDATA>/squirreljme/state(Windows)<PROGRAMDATA>/squirreljme/state(Windows)<XDG_STATE_HOME>/squirreljme(POSIX)<HOME>/.local/state/squirreljme(POSIX)
- Natives
<SQUIRRELJME_LIB_JVM>{~}<SQUIRRELJME_LIB_JVM_{SYSTEM}_{ARCH}>{~}<PROGRAMDATA>/squirreljme/natives(Windows)<PROGRAMDATA>/squirreljme/natives/{system}/{arch}(Windows)/lib/squirreljme/natives(POSIX)/lib/squirreljme/natives/{system}/{arch}(POSIX)
- Runtime Library
<SQUIRRELJME_RUNTIME_DIR>{~}
- Executable
- This always points to the current executable, if it can be determined.
- Temporary
<TMP>(Windows)<TEMP>(POSIX)/tmp(POSIX)[Cache]/sjme.tmp
- Libraries -- User provided JARs are loaded from here.
<SQUIRRELJME_LIBRARY_PATH>{~}[Data]/lib
- Data Bucket -- Non-volatile storage is here (RMS and DoJa Scratchpads).
[State]/data
- Extra Bucket
<SQUIRRELJME_BUCKET_EXTRA>{~}
Runtime Library Order
SquirrelJME will attempt to load its runtime library in this specific order
in either the [Runtime Library] directory or the [Data] directory if
the former is not set.
squirreljme-<VERSION>-fast.jarsquirreljme-<VERSION>.jarsquirreljme-<VERSION>-test.jarsquirreljme-<VERSION>-slow.jarsquirreljme-<VERSION>-slow-test.jarsquirreljme-fast.jarsquirreljme.jarsquirreljme-test.jarsquirreljme-slow.jarsquirreljme-slow-test.jar
Common Issues
TRYING TO RUN DoJa/Star (i-mode) SOFTWARE?: Both
DoJa and Star require the accompanying .jam file to be able
to load the titles as the Jar has no information itself on
how to start such titles. Some DoJa/Star software will also
require the .sp (Scratchpad) file as it relies on DLC which
must have already been downloaded, considering the services
for downloading such DLC are no longer online.
Environment and System Properties
System properties and environment variables are additional available in specific cases to modify default behavior of SquirrelJME from the command line.
Environment variables always take priority over system properties. Note that system properties are only available to the runtime, if a system is ultimately initialized purely in the native layer then system properties will have no effect.
Framing/Scaling
SquirrelJME supports framing and scaling of any MIDP Canvas, to override
the default scale factor you may specify:
- Framing -- Sets the default resolution of SquirrelJME
- System property:
cc.squirreljme.frame=WxH
- Environment Variable:
SQUIRRELJME_FRAME=WxH
- System property:
- Scaling -- Sets the output resolution that the frame is scaled to
- System property:
cc.squirreljme.scale=(multiplier|WxH)
- Environment Variable:
SQUIRRELJME_SCALE=(multiplier|WxH)
- System property:
ScritchUI Interface
- Preferred Interface -- This is the interface which will be attempted first.
- System Property (Standalone):
cc.squirreljme.scritchui=(name)
- Environment Variable:
SQUIRRELJME_SCRITCHUI_INTERFACE=(name)
- System Property (Standalone):
The following ScritchUI interfaces are provided by SquirrelJME, assuming that they are built and included:
win32-- Windows Win32 APIgtk2-- GTK 2.0
It is possible with the combination of the natives path and/or vendor-specific builds of SquirrelJME to have additional libraries available. Libraries placed in the natives path should have their name match the system that they are for.
Vendor-specific keycodes
SquirrelJME supports adjusting its input keycodes to match those of specific vendors.
- Vendor Keymaps -- Maps native device keys to vendor specific keys.
- System property:
cc.squirreljme.keymap=mapping
- Environment Variable:
SQUIRRELJME_VENDOR_KEY=mapping
- Where
mapping->cc.squirreljme.[vendorname].[device/series] - The following vendor mappings are supported at this time:
com.kddicom.motorola.a1000com.motorola(also used by SoftBank and Alcatel devices)com.motorola.triplets(also used by Sharp devices)com.motorola.v8(also used by Sharp devices)com.nokia(Also used by Samsung and Sony Ericsson)com.nokia.keyboard(Nokia C/E-Series in numpad mode)com.sagemcom.siemenskr.co.lgenet.rim.blackberry
- These properties' values are case-sensitive.
- If a matching CSV cannot be found for the passed argument, SquirrelJME will fail as a result.
- Note that the
motorolakey layout is also used by Alcatel and SoftBank,motorola.tripletsis also used by Sharp devices, andnokiais also used by Sony Ericsson and Samsung devices.
- System property:
Special file: URIs
These are special file: URIs in SquirrelJME, specified by using a special
authority. Within each authority, there may be an URI encoded target, this
is specified in brackets (<>). Note that it is shown here as being
unencoded so that it is readable and understood. This means that if the
contained value is <file://hello/> this will be encoded
as file%3A%2F%2Fhello%2F.
file://!%3Fx-squirreljme-all-volumes%3A%2F%2F%3F!/- All volumes root, this lists every internal library and all file system roots which are available.
file://!%3Fx-squirreljme-bucket%3A%2F%2F%3F!<...>/- Access to the bucket storage which contains non-volatile data such as RMS, DoJa ScratchPads, and user installed applications.
<0>or<data>for the data bucket.<1>or<libraries>for the library bucket.<2>or<extra>for the extra bucket.
file://!%3Fx-squirreljme-library%3A%2F%2F%3F!<...>/- Provides access to a specific library.
<...>may be a number indicating the library index (<0>).<...>may be the name of a Jar to access (<example.jar>).- The root directory may be opened as a data stream to access the raw library data.
file://!%3Fx-squirreljme-linear-scan%3A%2F%2F%3F!<uri:...>/- Walks through a binary file locating any known magic number and exposes a file system to access scanned content.
<uri:...>is the URI to load and access as binary data.
file://!%3Fx-squirreljme-zip%3A%2F%2F%3F!<uri:...>/- Provides access to reading arbitrary ZIP files.
<uri:...>is the URI to load and access as a ZIP file.
An example of referring to a library as a ZIP:
- Start with the target library:
file://!%3Fx-squirreljme-library%3A%2F%2F%3F!example.jar/
- URI encode the entire path:
file%3A%2F%2F%21%253Fx-squirreljme-library%253A%252F%252F%253F%21example.jar%2F
- Then insert it into the ZIP authority:
file://!%3Fx-squirreljme-zip%3A%2F%2F%3F!file%3A%2F%2F%21%253Fx-squirreljme-library%253A%252F%252F%253F%21example.jar%2F/
Using the Media Player from the Command Line
The media player may be started purely from the command line with the specified command:
squirreljme -Xentry:0 -jar system-app-media-player.jar
Note if you are on any UNIX/Posix system and are using Bash you will need
to quote URLs as Bash will try to interpret any exclamation point (!).
The following commands are available:
list- Lists the contents of the root directory.
list url- Lists the contents of the given URL.
play url (contentType)- Plays the given URL.
Listing contents will give a tab (\t) separated output in three columns:
- The content type.
- The URL of the content.
- The file name of the content.
For example, split into three rows:
inode/directory
file://!%3Fx-squirreljme-library%3A%2F%2F%3F!system-app-media-player.jar/
system-app-media-player.jar/
Then from the second argument, to list the contents of the JAR, copy the URL and run the list command:
list file://!%3Fx-squ<TRUNCATED>yer.jar/
This will give another list of tab (\t) separated columns:
audio/midi
file://!%3Fx-squ<TRUNCATED>yer.jar/11-Stucked-Convoi.mid
11-Stucked-Convoi.mid
Then to play the media, copy the URL into the given command with its content type:
play file://!%3Fx-squ<TRUNCATED>yer.jar/11-Stucked-Convoi.mid audio/midi
If you place the media file in the data and/or library directory, which is where non-volatile data is stored or your applications are installed, you can then play it via:
file://!%3Fx-squirreljme-bucket%3A%2F%2F%3F!data/music.midfile://!%3Fx-squirreljme-bucket%3A%2F%2F%3F!libraries/music.mid
While playing the output will be as followed. Progress updates will always
end in carriage return (\r) so that the last line is replaced. The starting
tilde (~) may be used to synchronize the output to find the next set of
messages to parse, while the ending caret (^) may be used to synchronize
the end of a line. The synchronization is mostly useful if you are parsing
the output from a script or another program, and you are not able to
differentiate between stdout and stderr as reliably.
The output template followed by an example:
~PlayerType: [99h 59m 59s 999999µs / 99h 59m 59s 999999µs] State (999)^
~MidiPlayer: [06s 244790µs / 04m 11s 812500µs] Started (400)^
States are as followed:
Closed (0)- The media is in the closed state.
Unrealized (100)- No data has yet been loaded.
Realized (200)- Data for the media has been loaded.
Prefetched (300)- The media and all resources are ready for playback.
Started (400)- The media is currently playing.
Undefined (999)- Not defined, the indicated number will be between any of the values indicated above.
The song will continue playing until it reaches the end.
Natives
Natives within SquirrelJME follow the same format as the host system:
- macOS:
library.dylib - UNIX-like and POSIX:
- Static --
liblibrary.a - Dynamic --
liblibrary.so
- Static --
- Windows:
library.dll
This should only be used as a baseline as a vendor and/or specific distribution may use a different format.
System and Architecture Names
SquirrelJME generally follows the proper name for a system and/or architecture in the naming scheme.
Architectures
The following names are used for architectures:
arm(32|64)(b|l)-- ARM Family.amd64-- AMD 64-bit CPU Family; Intel EM64T Family.emcripten-- Emscripten, compilation to JavaScript/WASM.ia16-- Intel 80286, 16-bit CPU Family.ia32-- Intel 80386, 32-bit CPU Family.ia64-- Itanium CPU Family.mips(32|64)(b|l)-- MIPS Family before R6.mips(32|64)(b|l)6-- MIPSR6 Family.powerpc(32|64)(b|l)-- PowerPC Family.riscv64-- RISC-V.
Systems
The following names are used for systems:
3ds-- Nintendo 3DS.android-- Android Mobile Platform.bios-- PC BIOS.bsd-- Any BSD.cygwin-- CygWin, a POSIX-like environment for Windows.dos-- DOS, MS-DOS, FreeDOS.efi-- Extensible Firmware Interface.emcripten-- Emscripten, compilation to JavaScript/WASM.freebsd-- FreeBSD.gamecube-- Nintendo GameCube.haiku-- Haiku.ieee1275of-- IEEE 1275, OpenFirmware, OpenBOOT.ios-- iOS, iPadOS; Not iPods.linux-- Linux.macintosh-- Classic Macintosh, previously System Software.macosx-- Mac OS X, or macOS, also known as Darwin.palmos-- PalmOS.playstation2-- Sony PlayStation 2.psp-- Sony PlayStation Portable.sdcc-- Small Device C Compiler Targets.switch-- Nintendo Switch.switch2-- Nintendo Switch 2.vita-- Sony PlayStation Vita.wii-- Nintendo Wii.wiiu-- Nintendo Wii U.windows-- Windows Desktop, not Windows CE.windowsce-- Windows CE, not Windows Desktop nor Windows Mobile.