Classroom Public page

Lab 0.0: Install and Verify

748 words

Pre-week-1 install check. ~10 minutes. Run this AFTER you have completed the install steps in SETUP.md. Verifies that every tool launches and a homebrew ROM loads.

Goal: confirm Mesen, SameBoy, bsnes-plus, and your hex editor are installed and working before week 1 begins.

Estimated time: 10 minutes

Prerequisites: completed installation per SETUP.md

Steps

Step 1: Launch Mesen

Open Mesen. The main window should appear with a blank canvas (no ROM loaded). Click File → Open ROM, then navigate to one of the homebrew NES ROMs you downloaded. Load it. The game should boot and run. Press whatever key Mesen has mapped to "Start" (default: Enter) to advance past the title screen.

If this works: Mesen is good. Close it.

If this fails: check that the ROM file is actually a .nes file (sometimes downloads bundle the ROM inside a .zip; you may need to extract first). Re-read SETUP.md's Mesen section.

Step 2: Launch SameBoy (no ROM needed)

Open SameBoy. The main window should appear. You do not have a Game Boy ROM yet (week 5 task); you are just verifying SameBoy launches.

Menu: View → Debugger. The debugger window should open. Close both windows.

If this works: SameBoy is good.

If this fails: re-read SETUP.md's SameBoy section.

Step 3: Launch bsnes-plus (no ROM needed)

Open bsnes-plus. The main window should appear. You do not have a SNES ROM yet; you are just verifying bsnes-plus launches.

Menu: Tools → Debugger. The debugger window should open. Close both windows.

If this works: bsnes-plus is good.

If this fails: re-read SETUP.md's bsnes-plus section.

Step 4: Open a file in your hex editor

Open your hex editor (HxD / Hex Fiend / Bless / hexedit). Open the same homebrew NES ROM you loaded in Mesen.

The hex editor should display the bytes in two columns: hex on the left, ASCII on the right. The first 4 bytes should be 4E 45 53 1A (which is "NES" + 0x1A, the INES file format magic number).

If you see this: the hex editor is working AND your ROM is a valid INES-format NES ROM. Close the hex editor without saving.

If you see different bytes: the file might be inside a zip wrapper, or might be a "FDS" (Famicom Disk System) image rather than a standard .nes file. Try downloading a different homebrew ROM.

Step 5: Open the 8bitworkshop browser sandbox

Open https://virtuscyberacademy.org/8bitworkshop/ in your browser. The 8bitworkshop interface should load with a code editor on the left and an emulator preview on the right.

Click the menu in the upper-left; select Platform → NES. The editor should switch to NES mode. Pick one of the example projects (e.g., "Hello World"); click the compile or run button. The example should compile and run in the preview.

If this works: the browser sandbox is good. Close the tab.

If this fails: try a different browser (Chrome / Firefox / Safari are all well-supported). If the academy's mirror is offline, the upstream https://8bitworkshop.com/ also works.

Expected output

By the end of the lab you have confirmed:

  • Mesen launches, loads a ROM, and runs the game
  • SameBoy launches and opens its debugger
  • bsnes-plus launches and opens its debugger
  • Your hex editor opens the homebrew ROM and shows recognizable bytes
  • The 8bitworkshop sandbox loads and runs an example NES project

Mark this lab complete in your journal. Move on to week 1.

Common pitfalls

  • Windows SmartScreen blocks the Mesen installer. Click "More info" → "Run anyway." Mesen is open-source and safe; SmartScreen sometimes flags unsigned installers on Windows
  • macOS Gatekeeper blocks SameBoy or bsnes-plus. Right-click the app and pick Open; macOS will prompt once and then remember the decision
  • Linux: the hex editor command not found. Install Bless via your distro's package manager (apt install bless on Debian/Ubuntu; dnf install bless on Fedora; pacman -S bless on Arch); or use hexedit which is more commonly preinstalled (apt install hexedit etc.)
  • Browser blocks the 8bitworkshop sandbox. Try disabling tracking-protection in the browser for the academy's domain; some strict tracking protectors flag the in-browser emulator's WebAssembly

Stretch (optional)

If everything worked first try, you have ~5 minutes left. Try:

  • Open Mesen's PPU viewer (Tools → PPU Viewer) and look at the sprite tiles in your loaded ROM. You will use this in weeks 2 and 4
  • Open Mesen's Debugger and look at the disassembly panel. You will use this in week 3
  • In your hex editor, scroll to byte offset 0x4000 and see what is there. (For a 32 KB NES ROM with 16 KB of PRG-ROM, byte 0x4010 onward is PRG-ROM)

Lab 0.0 v0.1. The first thing every SPK-101 student does.