amaterasu 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8be27ada9ca577ac19fee656335c0666f26de70e8cd46aa330485ef818bf74b
+  data.tar.gz: af21c688666e9b186498502adbd02c95dc72182be970e15f4044becb5cbf42bf
+SHA512:
+  metadata.gz: e783cb26b1a517ab3d3a96562606d9d2d50f36fb561c132b952f0240984e43c6e2bdb3778ffa570b444c9d2ef2b870c44865683aa00165d908858eb251ac79d9
+  data.tar.gz: 472bbd93c146ea25b94006e8259c5c8ffa7507c1312ef6d2d57079eaca892bbb7ccd33c7d1f9be76d9ddc736e5b8ed5debf33ae8a8ebfff121f0a0b1b06e576f

data/.gitignore

@@ -0,0 +1,14 @@
+.idea
+.tool-versions
+.vscode/
+.ruby-lsp/
+.yardoc/
+coverage/
+doc/
+docs/
+notes/
+rdoc/
+roms/
+tmp/
+*.json
+*.dump

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,54 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 120
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/amaterasu/gameboy/bus.rb'
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/ComparableBetween:
+  Enabled: false
+
+Style/EmptyLiteral:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/BitwisePredicate:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+ruby '4.0.3'
+
+# gem 'curses'
+# gem 'gosu'
+# gem 'raylib-bindings'
+
+gemspec
+
+group :development do
+  gem 'benchmark-ips'
+  gem 'debug'
+  gem 'memory_profiler'
+  gem 'pastel'
+  gem 'rake'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'rubocop-rspec'
+  gem 'stackprof'
+  gem 'steep', require: false
+  gem 'vernier', require: false
+  gem 'yard', require: false
+end
+
+group :test do
+  gem 'rspec'
+  gem 'rspec-benchmark'
+  gem 'simplecov'
+end

data/Gemfile.lock

@@ -0,0 +1,267 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    benchmark-ips (2.14.0)
+    benchmark-malloc (0.2.0)
+    benchmark-perf (0.6.0)
+    benchmark-trend (0.4.0)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.4)
+    ffi (1.17.4)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86-linux-gnu)
+    ffi (1.17.4-x86-linux-musl)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
+    fileutils (1.8.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.4)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    memory_profiler (1.1.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-benchmark (0.6.0)
+      benchmark-malloc (~> 0.2)
+      benchmark-perf (~> 0.6)
+      benchmark-trend (~> 0.4)
+      rspec (>= 3.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.86.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stackprof (0.2.28)
+    steep (2.0.0)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.17.0.4, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.2)
+      prism (>= 0.25.0)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 4.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 5)
+      uri (>= 0.12.0)
+    stringio (3.2.0)
+    strscan (3.1.8)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    tsort (0.2.0)
+    tty-color (0.6.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    vernier (1.10.0)
+    yard (0.9.43)
+    zeitwerk (2.8.2)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  benchmark-ips
+  debug
+  ffi
+  memory_profiler
+  pastel
+  rake
+  rspec
+  rspec-benchmark
+  rubocop
+  rubocop-performance
+  rubocop-rspec
+  simplecov
+  stackprof
+  steep
+  vernier
+  yard
+  zeitwerk
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  benchmark-ips (2.14.0) sha256=b72bc8a65d525d5906f8cd94270dccf73452ee3257a32b89fbd6684d3e8a9b1d
+  benchmark-malloc (0.2.0) sha256=37c68f0435261634026f584d79956a35325a3027e3e6b4cc8d7575aa10537e6b
+  benchmark-perf (0.6.0) sha256=fe2b01959f3de0f9dd34820d54ef881eb4f3589fccb7d17b63068ac92d7f9621
+  benchmark-trend (0.4.0) sha256=de5a02a9f443babefbbd97784759820decee8554a0c273d859c02a0990845d81
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
+  ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf
+  ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
+  ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
+  ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564
+  ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x86-linux-gnu) sha256=38e150df5f4ca555e25beca4090823ae09657bceded154e3c52f8631c1ed72cf
+  ffi (1.17.4-x86-linux-musl) sha256=fbeec0fc7c795bcf86f623bb18d31ea1820f7bd580e1703a3d3740d527437809
+  ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
+  fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  json (2.19.4) sha256=670a7d333fb3b18ca5b29cb255eb7bef099e40d88c02c80bd42a3f30fe5239ac
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  memory_profiler (1.1.0) sha256=79a17df7980a140c83c469785905409d3027ca614c42c086089d128b805aa8f8
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
+  pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  rbs (4.0.2) sha256=af75671e66cd03434cc546622741ebf83f6197ec4328375805306330bf78ef25
+  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-benchmark (0.6.0) sha256=1014adb57ec2599a2455c63884229f367a2fff6a63a77fd68ce5d804c83dd6cf
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.86.1) sha256=44415f3f01d01a21e01132248d2fd0867572475b566ca188a0a42133a08d4531
+  rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  rubocop-rspec (3.9.0) sha256=8fa70a3619408237d789aeecfb9beef40576acc855173e60939d63332fdb55e2
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  stackprof (0.2.28) sha256=4ec2ace02f386012b40ca20ef80c030ad711831f59511da12e83b34efb0f9a04
+  steep (2.0.0) sha256=6eb0ecc09637bbb54f0a5f2cf63daea6d3208ccace64b4f1107d976333605c30
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  strscan (3.1.8) sha256=aae2db611a225559f21ffbb71765c9a4e60fd262534a9ea84f4f11c7f32f679e
+  terminal-table (4.0.0) sha256=f504793203f8251b2ea7c7068333053f0beeea26093ec9962e62ea79f94301d2
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  vernier (1.10.0) sha256=5b1dc57012e08ed23e14f4d2943540140d454aa8434c7c35e7eb97befd4969bf
+  yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821
+  zeitwerk (2.8.2) sha256=7212a61311083c604184b1ea2574b9aa05cd14f855a0841c06985cabe9181d12
+
+RUBY VERSION
+  ruby 4.0.3
+
+BUNDLED WITH
+  4.0.6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fernando Eufrásio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+  <h1 style="font-size: 3em; font-weight: bold;">Amaterasu</h1>
+  <p>A <s>cycle-accurate?</s> Game Boy emulator written in Ruby.</p>
+</div>
+
+---
+
+## About
+
+This is, at its core, a research project. I always loved the concept of emulation and retro gaming, but as a web developer, low level development was never my strong suit. This is my first deep dive into the subject and it has been a great experience so far.
+
+I will try to document my progress as I try to create the emulator from the ground up (as cycle accurate as I can make it), this also helps me internalize some of the concepts about hardware emulation. I am finding it extremely challenging, but also very rewarding when your code actually behaves as the hardware would. I highly recommend for whoever is interested in learning those subjects.
+
+### Goals
+
+- Build a fully cycle-accurate emulator and try to replicate all the hardware quirks
+- Pass all the accuracy tests I can find and also document the progress of Passed/Failed tests
+- Try to reduce optimize code performance and memory usage as much as possible without losing code readability
+- Use a clean and idiomatic OOP approach for writing the code, extracting every self containing logic to a Class
+
+## Resources
+
+I'm heavily relying on the great work done by the community to document every possible (and obscure) behaviors that can be found in the Game Boy. I'll place here all the resources I'm using and some other relevant ones I find.
+
+### Docs
+
+- **[Pan Docs](https://gbdev.io/pandocs/)**: The single most comprehensive technical reference for the Game Boy. An absolute must-read.
+- **[Opcode Table](https://gbdev.io/gb-opcodes/optables/)**: Complete Opcode table for the Game Boy CPU instruction set.
+- **[RGBDS Docs](https://rgbds.gbdev.io/docs/v1.0.1/gbz80.7)**: Game Boy CPU instruction reference.
+- **[GB: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf)**: Great documentation about how the Game Boy hardware behaves, including some of the most obscure behaviors.
+- **[The Ultimate Game Boy Talk](https://www.youtube.com/watch?v=HyzD8pNlpwI)**: An amazing talk that provides a high-level overview of the hardware architecture.
+- **[GBDev Community](https://gbdev.io/)**: A fantastic hub for documentation, forums, and tools related to Game Boy development.
+
+### Tests
+
+- **[Mooneye Test Suite](https://github.com/Gekkio/mooneye-test-suite)**: Very complete suite of ROMs to test pretty much all aspects of the Game Boy.
+- **[Blargg's Test ROMs](https://gbdev.gg8.se/files/roms/blargg-gb-tests/)**: A suite of essential test ROMs for verifying the accuracy of CPU instructions, timing, and memory access.
+- **[Game Boy Test Roms](https://github.com/c-sp/game-boy-test-roms)**: A collection of different test suites for your Game Boy emulator, also has a [Wiki](https://deepwiki.com/c-sp/game-boy-test-roms/1-overview).
+
+### Other Emulators
+
+- **[SameBoy](https://github.com/LIJI32/SameBoy)**: Open source Game Boy (DMG) and Game Boy Color (CGB) emulator, written in portable C.
+- **[Mooneye GB](https://github.com/Gekkio/mooneye-gb)**: A Game Boy research project and emulator written in Rust.
+- **[LLD_gbemu](https://github.com/rockytriton/LLD_gbemu)**: A Game Boy emulator written in C as part of the Low Level Dev tutorial.
+- **[Rubyboy](https://github.com/sacckey/rubyboy)**: A Game Boy emulator written in Ruby.
+
+## Current Progress
+
+Here is a snapshot of the current implementation status of the Game Boy's hardware components.
+
+### Address Bus
+
+- [x] Receives all components by dependency injection.
+- [x] Creates a public API with read_byte and write_byte methods.
+- [x] Delegates the memory read and write to the correct components.
+- [x] Correctly mapped the address range for the Cartridge, External RAM, VRAM, Echo RAM, OAM, HRAM and most of the IO registers.
+- [ ] Still pending to wire and implement all the APU registers.
+
+### CPU
+
+- [x] All base opcodes implemented with the correct timing.
+- [x] All CB prefixed opcodes implemented with the correct timing.
+- [x] Interrupts handling (IME, IE, IF registers and service routines).
+
+### Timer
+
+- [x] Resets the value of the internal counter on any write to DIV.
+
+### DMA Controller
+
+- [x] Correctly latches the value used to start the transfer, if $FF46 is read return this value.
+- [x] Correctly implemented the 1 cycle delay before starting the actual transfer.
+- [x] Correctly implemented the 160 cycles (1 byte per cycle) transfer.
+- [x] Correctly implemented the Bus locking mechanism, whila DMA is active, the CPU should only be able to read/write in the IO + HRAM address range (0xFF00 - 0xFFFF).
+- [x] Correctly implemented the DMA restart logic, should reset the cycles to 0, source address to the new source * $100 and target address to 0xFE00.
+
+### Serial Port
+
+- [x] Correctly implemented the behavior for registers SC and SB.
+- [x] Captures the message received to a message buffer to allow printing.
+- [x] Requests serial interrupt when transfer is completed.
+
+## Accuracy Checks
+
+| Suite    | Passed | Failed   | Total  |
+|:---------|-------:|---------:|-------:|
+| Blargg   |   18   |    3     |   21   |
+| Mooneye  |    -   |    -     |    -   |
+
+
+### Blargg Tests
+
+| Test                                  |  Status  |
+|---------------------------------------|:--------:|
+| `cpu_instrs/01-special.gb`            |    ✅    |
+| `cpu_instrs/02-interrupts.gb`         |    ✅    |
+| `cpu_instrs/03-op sp,hl.gb`           |    ✅    |
+| `cpu_instrs/04-op r,imm.gb`           |    ✅    |
+| `cpu_instrs/05-op rp.gb`              |    ✅    |
+| `cpu_instrs/06-ld r,r.gb`             |    ✅    |
+| `cpu_instrs/07-jr,jp,call,ret,rst.gb` |    ✅    |
+| `cpu_instrs/08-misc instrs.gb`        |    ✅    |
+| `cpu_instrs/09-op r,r.gb`             |    ✅    |
+| `cpu_instrs/10-bit ops.gb`            |    ✅    |
+| `cpu_instrs/11-op a,(hl).gb`          |    ✅    |
+| `instr_timing.gb`                     |    ✅    |
+| `mem_timing/01-read_timing.gb`        |    ✅    |
+| `mem_timing/02-write_timing.gb`       |    ✅    |
+| `mem_timing/03-modify_timing.gb`      |    ✅    |
+| `mem_timing_2/01-read_timing.gb`      |    ✅    |
+| `mem_timing_2/02-write_timing.gb`     |    ✅    |
+| `mem_timing_2/03-modify_timing.gb`    |    ✅    |
+| `interrupt_time.gb`                   |    ❌    |
+| `halt_bug.gb`                         |    ❌    |
+| `dmg_sound.gb`                        |    ❌    |

data/Steepfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature 'sig'
+  check 'lib'
+  library 'optparse'
+end

data/exe/amaterasu

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RubyVM::YJIT.enable if defined?(RubyVM::YJIT)
+
+require_relative '../lib/amaterasu'
+
+options = Amaterasu::CLI.parse(ARGV)
+
+if options[:profiling]
+  require 'stackprof'
+
+  StackProf.start(mode: options[:profiling].to_sym)
+
+  at_exit do
+    StackProf.stop
+    StackProf.results(
+      "tmp/#{Time.now.to_i}-#{options[:profiling]}-emulator-results.dump"
+    )
+  end
+end
+
+Amaterasu::Emulator.new(**options).start

data/lib/amaterasu/cartridge/mbc1.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  class Cartridge
+    # Models the MBC1 chip inside the Game Boy cartridge.
+    #
+    # 0x0000 - 0x3FFF => ROM Bank X0
+    # 0x4000 - 0x7FFF => ROM Bank 01-7F (1 - 127)
+    #
+    # Can switch between Modes 0 and 1.
+    class Mbc1
+      def initialize(rom, ram)
+        @rom = rom
+        @ram = ram
+
+        @rom_banks = rom.rom_size / ROM_BANK_SIZE
+        @ram_enabled = false
+        @banking_mode = 0
+        @rom_banking_reg1 = 0b00001
+        @rom_banking_reg2 = 0b00
+      end
+
+      def write_byte(address, value)
+        if address <= 0x1FFF
+          @ram_enabled = true if (value & 0xF) == 0xA
+        elsif address <= 0x3FFF
+          value &= 0b11111
+          @rom_banking_reg1 = value.zero? ? 1 : value
+        elsif address <= 0x5FFF
+          @rom_banking_reg2 = value & 0b11
+        elsif address <= 0x7FFF
+          @banking_mode = value & 1
+        else
+          return 0xFF if @ram.nil? || !@ram_enabled
+
+          @ram.write_byte(address:, value:)
+        end
+      end
+
+      # TODO: Implement banking mode logic for reads
+      def read_byte(address)
+        if address <= 0x3FFF
+          @rom.read_byte(address)
+        elsif address <= 0x7FFF
+          selected_bank = (@rom_banking_reg2 << 5) | @rom_banking_reg1
+          bank_offset = selected_bank * ROM_BANK_SIZE
+          @rom.read_byte(address - 0x4000 + bank_offset)
+        else
+          return 0xFF if @ram.nil? || !@ram_enabled
+
+          @ram.read_byte(address:)
+        end
+      end
+    end
+  end
+end