emuname documentation 2016 Mar 18

Plugins - Class Emuname - Abstract Class ENPlugin - Interface ENMethod - Class ENEvent
Class PixelCanvas - Class NES - Class Memory - Class Mapper - Class CPU6502 - Class PPU2C02 - Script engine

Plugins

To create a plugin

• Add the path to emuname.jar to your compiler's classpath
• Write an ENPlugin subclass, importing net.shygoo.emuname.*
• Write a constructor for the class which has no parameters and calls super(String id, int initOrder)
• Override init(Emuname emuname)
• You may use emuname.on to add methods to hooks, and emuname.addPluginMenuItem to add plugin items to the Plugins menu
• JAR your class(es), with the Main-Class attribute of the JAR's manifest set to your ENPlugin subclass's fully qualified name
• Drop the JAR in emuname's plugins directory

Example

This plugin uses the active Graphics2D object of every frame to draw "Hello world" to the screen.

MyPlugin.java

package example.plugin; import net.shygoo.emuname.*; import java.awt.Graphics2D; public class MyPlugin extends ENPlugin { public MyPlugin(){ super("my_plugin", 0); } public void init(Emuname emuname){ emuname.on("drawend", (e) -> { e.getGraphics().drawString("Hello World!", 20, 20); }); } }

Manifest.txt

Manifest-Version: 1.0 Main-Class: example.plugin.MyPlugin

build.bat

@echo off set /p emunamejar="Enter path to emuname.jar: " mkdir bin javac -d bin -cp .;%emunamejar% MyPlugin.java cd bin jar -cmf ../Manifest.txt ../MyPlugin.jar . cd .. rmdir /q /s bin pause

MyPlugin.zip

Available plugin hooks

ID	Execution time	ENEvent type
drawstart	Before every frame is drawn (emuname.screen.preframe)	EVENT_GRAPHICS
drawend	After every frame is drawn (emuname.screen.postframe)	EVENT_GRAPHICS
stepstart	Before every CPU step (emuname.nes.prestep)	EVENT_NULL
stepend	After every CPU step (emuname.nes.poststep)	EVENT_NULL
click	When mouse clicks the game screen	EVENT_MOUSE
wheel	When mouse wheel is moved over the game screen	EVENT_WHEEL
mouseover	When mouse enters the game screen	EVENT_MOUSE
mouseout	When mouse exits the game screen	EVENT_MOUSE
mousemove	When mouse moves over the game screen	EVENT_MOUSE
mousedown	When mouse button is pressed on the game screen	EVENT_MOUSE
mouseup	When mouse button is released on the game screen	EVENT_MOUSE
keyup	When key is released over the game screen	EVENT_KEY
keydown	When key is pressed over the game screen	EVENT_KEY

Default plugins

ID	Initiation order	JAR file
default_menus	0	DefaultMenus.jar
debugger	1	Debugger.jar
crt_effects	1	CRTEffects.jar

Default plugin menu items

ID	Defining plugin	Caption	Function	Java class
dbg	default_menus	Debugging	Debugger submenu	JMenu
dbg_memory	debugger	> Memory...	Shows memory window	JMenuItem
dbg_scanner	debugger	> Memory scanner...	Shows memory scanner window	JMenuItem
dbg_commands	debugger	> Commands...	Shows CPU commands window	JMenuItem
games	default_menus	Games	Submenu for game-specific plugins	JMenu
games_balloon_fight_mouse	balloon_fight_mouse	> Balloon fight dragger	Toggles Balloon Fight entity drag n' drop	JMenuItem
vid	default_menus	Video filters	Submenu for video filters	JMenu
vid_smoothing	crt_effects	> Bilinear smoothing	Toggles Bilinear smoothing	JCheckBoxMenuItem
vid_scanlines	crt_effects	> CRT Scanlines	Toggles CRT-like scanlines	JCheckBoxMenuItem
vid_noise	crt_effects	> CRT Noise	Toggles CRT-like noise	JCheckBoxMenuItem

Class Emuname

net.shygoo.emuname.Emuname extends javax.swing.JFrame

The main window.

Fields

NES

nes

Methods

NES	getNes()	Returns the NES object
PixelCanvas	getScreen()	Returns the PixelCanvas component
Config	getConfig()	Returns the config object
System
void	reset()	Soft-resets game
void	pause()	Pauses emulation
void	resume()	Resumes emulation
void	end()	Stops emulation and shows the rom selection screen
Plugin management
int	on(String hookId, ENMethod method)	Adds a method to the hook specified by hookId Returns a unique numeric ID for the method
void	off(String hookId, int id)	Removes a method from the hook specified by hookId
ENPlugin	getPlugin(String id)	Returns a plugin object by id
String[]	getPluginIds()	Returns an array of existing plugin IDs
void	addPluginMenuItem(String id, JMenuItem menuItem)	Adds menuItem to the plugin menu
void	addPluginMenuItem(String id, String attachToId, JMenuItem menuItem)	Adds menuItem to an existing menu item specified by attachToId
void	addPluginMenuItem(String id, JFrame frame, String itemCaption)	Adds menuItem that shows frame when clicked
void	addPluginMenuItem(String id, String attachToId, JFrame frame, String itemCaption)	Adds a MenuItem to an existing menu item specified by attachToId Shows frame when clicked
JMenuItem	getPluginMenuItem(String id)	Returns a plugin menu item by id
String[]	getPluginMenuItemIds()	Returns an array of existing plugin menu IDs

Abstract Class ENPlugin

net.shygoo.emuname.ENPlugin

Abstract class for subclassing third party emuname plugins. Subclasses must invoke super(String id, int initOrder) to define the plugin's final identification string and initiation order.

Constructor

-

ENPlugin(String id, int initOrder)

Methods

abstract void	init(Emuname emuname)	Serves as a post-constructor, providing access to emuname
String	getId()	Returns the plugin's ID string
int	getInitOrder()	Returns the plugin's initiation order

Interface ENMethod

net.shygoo.emuname.ENMethod

Functional interface for the plugin hooks of emuname.

Methods

void

run(ENEvent e)

The method

Class ENEvent

net.shygoo.emuname.ENEvent

Wrapper class for various events. Instance methods will throw a runtime exception if they don't correspond with the event type.

Constructors

-	ENEvent()	Constructs an ENEvent object with the type set to EVENT_NULL
-	ENEvent(MouseEvent e, double xScale, double yScale)	Constructs an ENEvent object with the type set to EVENT_MOUSE
-	ENEvent(MouseWheelEvent e, double xScale, double yScale)	Constructs an ENEvent object with the type set to EVENT_WHEEL
-	ENEvent(KeyEvent e)	Constructs an ENEvent object with the type set to EVENT_KEY
-	ENEvent(Graphics2D g)	Constructs an ENEvent object with the type set to EVENT_GRAPHICS

Fields

static int	EVENT_NULL	(0)
static int	EVENT_MOUSE	(1)
static int	EVENT_WHEEL	(2)
static int	EVENT_KEY	(3)
static int	EVENT_GRAPHICS	(4)

Methods

static String	getTypeName(int type)	Returns the name of an event type number
int	getType()	Returns the instance's event type number
String	getTypeName()	Returns the instance's event type name
For EVENT_MOUSE and EVENT_WHEEL
int	getX()	Returns the scaled x position of the cursor on the game screen
int	getY()	Returns the scaled y position of the cursor on the game screen
For EVENT_MOUSE
MouseEvent	getMouseEvent()	Returns the associated AWT MouseEvent
For EVENT_WHEEL
MouseWheelEvent	getMouseWheelEvent()	Returns the associated AWT MouseWheelEvent
int	getScrollAmount()	Returns the event's mouse wheel scroll amount
For EVENT_KEY
KeyEvent	getKeyEvent()	Returns the associated AWT KeyEvent
int	getKeyCode()	Returns the event's key code
char	getKeyChar()	Returns the event's key character
For EVENT_GRAPHICS
Graphics2D	getGraphics()	Returns the associated AWT Graphics2D

Class NES

net.shygoo.emuname.NES

Constructor

-

NES()

Constructs a NES emulator

Fields

INES file format constants
static int	INES_HEADERSIZE	(16) iNES rom header size
static int	INES_HEADER_PRGROM_SIZE	(0x04) iNES rom offset of program rom size byte
static int	INES_HEADER_CHRROM_SIZE	(0x05) iNES rom offset of character rom size byte
static int	INES_HEADER_FLAGS6	(0x06) iNES rom offset of flags6 byte
static int	INES_HEADER_FLAGS7	(0x07) iNES rom offset of flags7 byte
System memory I/O register offsets
static int	REG_PPU_CTRL1	(0x2000) PPU Control 1
static int	REG_PPU_CTRL2	(0x2001) PPU Control 2
static int	REG_PPU_STATUS	(0x2002)
static int	REG_PPU_OAM_ADDRESS	(0x2003)
static int	REG_PPU_OAM_IO	(0x2004)
static int	REG_PPU_SCROLL	(0x2005)
static int	REG_PPU_ADDRESS	(0x2006)
static int	REG_PPU_IO	(0x2007)
static int	REG_APU_PULSE1_CTRL	(0x4000)
static int	REG_APU_PULSE1_RC	(0x4001)
static int	REG_APU_PULSE1_FT	(0x4002)
static int	REG_APU_PULSE1_CT	(0x4003)
static int	REG_APU_PULSE2_CTRL	(0x4004)
static int	REG_APU_PULSE2_RC	(0x4005)
static int	REG_APU_PULSE2_FT	(0x4006)
static int	REG_APU_PULSE2_CT	(0x4007)
static int	REG_APU_TRI_CTRL1	(0x4008)
static int	REG_APU_TRI_CTRL2	(0x4009)
static int	REG_APU_TRI_FREQ1	(0x400A)
static int	REG_APU_TRI_FREQ2	(0x400B)
static int	REG_APU_NOISE_CTRL1	(0x400C)
static int	REG_APU_NOISE_CTRL2	(0x400D)
static int	REG_APU_NOISE_FREQ1	(0x400E)
static int	REG_APU_NOISE_FREQ2	(0x400F)
static int	REG_APU_DM_CTRL	(0x4010)
static int	REG_APU_DM_DA	(0x4011)
static int	REG_APU_DM_ADDRESS	(0x4012)
static int	REG_APU_DM_LENGTH	(0x4013)
static int	REG_PPU_OAM_DMA	(0x4014)
static int	REG_APU_VCS	(0x4015)
static int	REG_JOYPAD1	(0x4016)
static int	REG_JOYPAD2	(0x4017)
Joypad strobe positions
static int	BUTTON_A	(0)
static int	BUTTON_B	(1)
static int	BUTTON_SELECT	(2)
static int	BUTTON_START	(3)
static int	BUTTON_UP	(4)
static int	BUTTON_DOWN	(5)
static int	BUTTON_LEFT	(6)
static int	BUTTON_RIGHT	(7)
Hardware
CPU6502	cpu	Central processing unit
PPU2C02	ppu	Picture processing unit
APU2A03	apu	Audio processing unit (not started)
Memory	mem	System/CPU memory
Mapper	mapper	Cartridge memory mapper
Miscellaneous
byte[]	rom	iNES rom file data

Methods

void	resetMemory()	Reinstantiates mem
void	loadRom(String path)
void	runUntilVBlank()
void	dbgBreak()	Ends the current runUntilVBlank loop
void	prestep()	Does nothing by default Invoked before every CPU step
void	poststep()	Does nothing by default Invoked after every CPU step

Class CPU6502

net.shygoo.hw.CPU6502

Constructor

-

CPU6502(Memory mem)

Constructs a new CPU6502 hardware emulator that uses mem as memory space for programs

Methods

int	getPC()	Returns program counter offset
int	getAC()	Returns Accumulator value
int	getXR()	Returns X index register value
int	getYR()	Returns Y index register value
int	getSP()	Returns Stack pointer value
int	getSR()	Returns Status register value
void	setPC(int value)	Sets Program counter offset
void	setAC(int value)	Sets Accumulator value
void	setXR(int value)	Sets X index register value
void	setYR(int value)	Sets Y index register value
void	setSP(int value)	Sets Stack pointer value
void	setSR(int value)	Sets Status register value
void	clock(int cycles)
void	nonMaskableInterrupt()
void	reset()
int	step()
void	setMemory(Memory mem)

Class PPU2C02

net.shygoo.hw.PPU2C02

Constructor

-

PPU2C02(Memory chrMem)

Constructs a PPU2C02 hardware emulator that uses chrMem as character memory space

Fields

Mirroring mode constants
static int	MIRRORING_ONESCREEN	(0)
static int	MIRRORING_HORIZONTAL	(1)
static int	MIRRORING_VERTICAL	(2)
static int	MIRRORING_FOURSCREEN	(3)
Hardware
Memory	mem	PPU main memory
byte[0x100]	oam	PPU object attribute (sprite) memory
Memory	chrMem	Cartridge character memory
Internal states
int	scrollX
int	scrollY
int	scrollState	// 0 = x, 1 = y // todo consts
int	address
int	addressState	// 0 = address msb, 1 = address lsb //todo consts
int	nameTableOffset
int	increment
int	pTableSprOffset
int	pTableBgOffset
int	sprSize
boolean	nmi
boolean	monochrome
boolean	clipBg
boolean	clipSpr
boolean	showBg
boolean	showSpr
int	bgColor
Miscellaneous
int[0x10000]	display	RGB888 frame buffer
int	currentScanline	// max at 262

Methods

void	incAddress() // todo make private
int	readNext()
void	writeNext(int value)
void	resetScanlines()
boolean	getSprite0Hit()	// todo isSpriteZeroHit()
boolean	getScanline8Sprites()	// todo change to isSpriteOverflow()
void	drawSpritesLine() // todo make private
void	drawBackgroundLine() // todo make private
void	drawScanline()
void	setChrMem(Memory chrMem)
void	resetMemory()
void	setMirroringMode(int mirroringMode)	Sets the nametable screen mirroring mode

Abstract Class Memory

net.shygoo.misc.Memory

Methods

abstract int	read(int offset, boolean doEvents)	return integer from memory
abstract void	write(int offset, int value, boolean doEvents)	write integer to memory
int	read(int offset)	wrapper for read that defaults doEvents to true // TODO make false
void	write(int offset, int value)	wrapper for write that defaults doEvents to true // TODO make false

Abstract Class Mapper

net.shygoo.emuname.mapper.Mapper

Constructor

-

Mapper(NES nes)

Constructs a Mapper

Fields

Hardware
Memory	chrMem	Memory wrapper for cartridge character rom / video ram
Memory	prgMem	Memory wrapper for cartridge program rom

Methods

int	getDefaultPrgBankA()	Get load-time program bank A number
int	getDefaultPrgBankB()	Get load-time program bank B number
void	setPrgBankA(int bank)
void	setPrgBankB(int bank)
int	getPrgBankA()
int	getPrgBankB()
void	assignDefaultBanks()	todo change to setPrgBanksDefault
String	getName()

Class PixelCanvas

net.shygoo.component.PixelCanvas extends javax.swing.JPanel

Constructor

-

PixelCanvas(int width, int height, int[] rgbArray)

Constructs a PixelCanvas
paint() is overridden to draw whatever is in the rgbArray buffer

Methods

void	setScale(int scale)	Sets the scale of the component
int	getScale()	Returns the current scale of the component
void	setDefaultDrawingEnabled(boolean setting)	Prevents rgbArray from drawing to the component if false Should be used when the default drawing technique needs to be replaced (eg upscaling filters)
boolean	getDefaultDrawingEnabled()	Returns defaultDrawing
void	setImageSmoothingEnabled(boolean setting)	Enables or disables bilinear smoothing based on setting // Not needed, todo move to plugin
void	setRgbArray(int[] rgbArray)	Changes the rgb buffer
Graphics2D	getActiveG2d()	Returns the last Graphics2D object passed to paint() Should be used in the postframe() method for correct timing
void	preframe()	Can be overriden to provide a hook in paint() for before the image is drawn Changes can be made to rgbArray here Changes can be made to the Graphics2D object here if default drawing is disabled
void	postframe()	Can be overriden to provide hook in paint() for after the image is drawn Changes can be made to the current Graphics2D object here

Script engine

Global properties

emuname

Reference to the Emuname object

nes

Reference to the NES object

frameEvents

Management object for a list of javascript functions to be called by the emulation thread during every VBlank phase
• frameEvents.add(callback) -- Adds a function and returns its ID
• frameEvents.remove(id) -- Removes a function by its ID
• frameEvents.clear() -- Removes all functions
• frameEvents.run() -- Executes all functions (called automatically)

For built in globals, refer to the Nashorn API documentation or try print(Object.getOwnPropertyNames(this))

Example scripts

Sink all enemy players in Balloon Fight:

var OFFSET_ENEMIES_Y = 0x009C; var ENEMIES_MAX_COUNT = 6; frameEvents.add(function(){ for(var i = 0; i < ENEMIES_MAX_COUNT; i++){ var offsetY = OFFSET_ENEMIES_Y + i; var y = nes.mem.read(offsetY); nes.mem.write(offsetY, y + 5); } });

Frame buffer color inversion:

frameEvents.add(function(){ for(var i = 0; i < nes.ppu.display.length; i++){ nes.ppu.display[i] = ~nes.ppu.display[i]; } });

shygoo.net