sergioluis / chipeit Goto Github PK

Developer: @mikelcaz
Reviewer: @SergioLuis
Integrator: @SergioLuis

The application must be able of starting and stopping a beep-alike sound. For now, choose a tone. The user might be able to customize it later, but for now, whatever you decide is OK.

I ask you to implement this because you don't need to know a lot of Android to make an already existing application play sounds. You can even implement it on a button press / release for testing, it will be later moved wherever it is needed.

Developers: @SergioLuis
Reviewers: @mikelcaz

Set up a CI system. Check out Travis CI first.

Developer: @jhvargas3112
Reviewer: @mikelcaz
Integrator: @SergioLuis

7xkk - ADD Vx, byte
Set Vx = Vx + kk.

Adds the value kk to the value of register Vx, then stores the result in Vx.

8xy0 - LD Vx, Vy
Set Vx = Vy.

Stores the value of register Vy in register Vx.

8xy1 - OR Vx, Vy
Set Vx = Vx OR Vy.

Performs a bitwise OR on the values of Vx and Vy, then stores the result in Vx. A bitwise OR compares the corrseponding bits from two values, and if either bit is 1, then the same bit in the result is also 1. Otherwise, it is 0.

8xy2 - AND Vx, Vy
Set Vx = Vx AND Vy.

Performs a bitwise AND on the values of Vx and Vy, then stores the result in Vx. A bitwise AND compares the corrseponding bits from two values, and if both bits are 1, then the same bit in the result is also 1. Otherwise, it is 0.

8xy3 - XOR Vx, Vy
Set Vx = Vx XOR Vy.

Performs a bitwise exclusive OR on the values of Vx and Vy, then stores the result in Vx. An exclusive OR compares the corrseponding bits from two values, and if the bits are not both the same, then the corresponding bit in the result is set to 1. Otherwise, it is 0.

8xy6 - SHR Vx {, Vy}
Set Vx = Vx SHR 1.

If the least-significant bit of Vx is 1, then VF is set to 1, otherwise 0. Then Vx is divided by 2.

8xyE - SHL Vx {, Vy}
Set Vx = Vx SHL 1.

If the most-significant bit of Vx is 1, then VF is set to 1, otherwise to 0. Then Vx is multiplied by 2.

Developer: @ugedo
Reviewer: @SergioLuis
Integrator: @SergioLuis

Implement the following instructions:

3xkk - SE Vx, byte
Skip next instruction if Vx = kk.

The interpreter compares register Vx to kk, and if they are equal, increments the program counter by 2.

4xkk - SNE Vx, byte
Skip next instruction if Vx != kk.

The interpreter compares register Vx to kk, and if they are not equal, increments the program counter by 2.

5xy0 - SE Vx, Vy
Skip next instruction if Vx = Vy.

The interpreter compares register Vx to register Vy, and if they are equal, increments the program counter by 2.

Annn - LD I, addr
Set I = nnn.

The value of register I is set to nnn.

Bnnn - JP V0, addr
Jump to location nnn + V0.

The program counter is set to nnn plus the value of V0.

Cxkk - RND Vx, byte
Set Vx = random byte AND kk.

The interpreter generates a random number from 0 to 255, which is then ANDed with the value kk. The results are stored in Vx. See instruction 8xy2 for more information on AND.

Fx1E - ADD I, Vx
Set I = I + Vx.

The values of I and Vx are added, and the results are stored in I.

Fx55 - LD [I], Vx
Store registers V0 through Vx in memory starting at location I.

The interpreter copies the values of registers V0 through Vx into memory, starting at the address in I.

Fx65 - LD Vx, [I]
Read registers V0 through Vx from memory starting at location I.

The interpreter reads values from memory starting at location I into registers V0 through Vx.

Assigned people

Developer:
Reviewer:

Description

In order to save/load a game state, is necessary to be able to save/load the following data:

• Main memory (which contains both the code and the data)
• Registers
  • General purpose registers, from V{0} to V{e}
  • Carry / flag register V{f}
  • Stack Pointer (SP)
  • Program Counter (PC)
• Graphic memory

The API must be extended somehow to achieve all that. Note that saving a image from the graphic memory is not enough, as is expected to be loaded later. Left that kind of stuff (that could be useful for previews and snapshots) out of the Chipeit API.

Saving stuff implies a runtime behavior, but loading it doesn't as long a new Chipeit object can be instantiated...

Related work

• Preview #44
• Snapshots #45

Developer: @SergioLuis
Reviewer: @mikelcaz @jhvargas3112 @ugedo

Fill the CHIP-8 Technical Reference Wiki page. The work is half done.

Work for the reviewers: fill the typos (if any) and get familiar with the CHIP-8 internals.

Assigned people

Developer:
Reviewer:

Description

CHIP-8 features a monochrome screen: what colors are used is unknown to the games. Users should be able to select which colors do they want.

Challenges:

• Letting them to select similar colors is problematic.

Is desirable:

• Provide users with the best color (by contrast) automatically.
• Add an option to change the color automatically while playing, to resemble something like Adventure.

A way of documenting code must be stablished. Procedures and conventions about how, what, who and where documentation is needed.

Alternatives can be considered here. The result must end up in the wiki.

Assigned people

Developer:
Reviewer:

Description

The current keyboard seems too simple, or too unrelated with emulation, or something like that. Must be reworked to look nice.

Related work

A future feature is discussed about make the keys light if they are relevant in the game. Should be taken in consideration.

Assigned people

Developer:
Reviewer:

Description

The "game library" and "saved games" grids should show thumbs of the games. The second should show the screen last state (see the issue about saving the graphic memory), what the "game library" thumbs should show is to be defined.

Related work

• Loading/saving the graphic memory #38

Dependencies:

• Game library #37
• Save game grid #43

Assigned people

Developer:
Reviewer:

https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/

Assigned people

Developer:
Reviewer:

Description

When trying to run the application on an Android 4.4 (KitKat, API Level 19) device (CHIPEIT minimum Android version targeted) it crashes and show the next message:

Pending to fill

This can be reproduced both on real hardware and on an emulator.
At first it seemed a problem with the splash screen animation's library, but the problem persists when that animation is removed, and when the splash screen is completely bridged to the game library.

Remarks: This happens only with API level 19. API level 20 is for wearables, and API level 21 works OK (at least on emulator)

Developers: @ugedo @jhvargas3112
Reviewers: @mikelcaz @SergioLuis

Design the Android User Interface.

This means: design it, do NOT code it. The functionality the UI must cover is:

• Load a game from the system's file manager.
  • Take a look at how you can upload files using Google Drive.
• Quick load a recent game. Load a saved game.
• Play the game
  • CHIP-8 uses 16 keys, from 0 to 9 and from A to F.
  • CHIP-8 uses a 64x32 monochrome screen. Be sure to maintain the aspect ratio in the game.
• Quick save a game.
• Screenshot the game's screen and share it (using the Android API. If you need examples, take a look at how you can share a tweet on its official Android application).

You can upload the mockups to a top-level directory in the repository. We'll use this issue to discuss them.

Assigned people

Developer:
Reviewer:

Description

Currently, the game library shines a temporal GUI based on a game list. The final game library should be implemented to replace it, as described initially.

The new interface should provide users with:

• A way to search and add ROMs from the storage (currently, only built-in ROMs are available!). Note: should them be played automatically, or just added?
• A way to manage ROMs as described in the UI design.

Challenges:

• How storage-resident ROMs are tracked (thumbs could be problematic if the idea was to save just the path).
• How to resolve inconsistencies (e.g. ROMs erased from the storage).

Is desirable:

• Provide users with a way to erase ROMs from the storage or just removing it from the grid.

Related work

The UI design: #4

To be extended with:

• "Save game" GUI: #43
• Game previews: #44

Developer: @SergioLuis
Reviewer: Nobody
Integrator: @SergioLuis

Integrate the tasks where the instruction set was implemented.
Make sure that the result has the style the team agreed on.

Developer: @SergioLuis
Reviewer: @mikelcaz
Integrator: @mikelcaz

By the end of #2, the Program Counter is updated while reading the instruction to be executed, at the Cpu class. This can lead to some problems with the instructions that can directly modify the Program Counter (jump instructions, skip instructions), and the one instruction that halts the execution until a keyboard key is pressed and then released.

A first approach to solve that last point was rewinding the Program Counter by two, but it is way better to avoid updating it at all. And another plus of this approach is that the instructions are much more testable, checking how the Program Counter changed at the end of each one.

So, things to do:

• Change the way the Program Counter is used to read the instruction in the Cpu class.
• Update the already implemented instructions to update the Program Counter at the end of instruction execution.
• Update the already implemented tests to check the Program Counter.

Assigned people

Developer:
Reviewer:

Description

The user should be able to take a snapshot of the virtual CHIPEIT screen.

Related work

The UI design: #4

Dependencies:

• Loading/saving the graphic memory #38

Developer: @mikelcaz
Reviewer: @SergioLuis
Integrator: @SergioLuis

Implement the following instructions:

8xy4 - ADD Vx, Vy
Set Vx = Vx + Vy, set VF = carry.

The values of Vx and Vy are added together. If the result is greater than 8 bits (i.e., > 255,) VF is set to 1, otherwise 0. Only the lowest 8 bits of the result are kept, and stored in Vx.

8xy5 - SUB Vx, Vy
Set Vx = Vx - Vy, set VF = NOT borrow.

If Vx > Vy, then VF is set to 1, otherwise 0. Then Vy is subtracted from Vx, and the results stored in Vx.

8xy7 - SUBN Vx, Vy
Set Vx = Vy - Vx, set VF = NOT borrow.

If Vy > Vx, then VF is set to 1, otherwise 0. Then Vx is subtracted from Vy, and the results stored in Vx.

9xy0 - SNE Vx, Vy
Skip next instruction if Vx != Vy.

The values of Vx and Vy are compared, and if they are not equal, the program counter is increased by 2.

Dxyn - DRW Vx, Vy, nibble
Display n-byte sprite starting at memory location I at (Vx, Vy), set VF = collision.

The interpreter reads n bytes from memory, starting at the address stored in I. These bytes are then displayed as sprites on screen at coordinates (Vx, Vy). Sprites are XORed onto the existing screen. If this causes any pixels to be erased, VF is set to 1, otherwise it is set to 0. If the sprite is positioned so part of it is outside the coordinates of the display, it wraps around to the opposite side of the screen. See instruction 8xy3 for more information on XOR, and section 2.4, Display, for more information on the Chip-8 screen and sprites.

Fx07 - LD Vx, DT
Set Vx = delay timer value.

The value of DT is placed into Vx.

Fx15 - LD DT, Vx
Set delay timer = Vx.

DT is set equal to the value of Vx.

Fx18 - LD ST, Vx
Set sound timer = Vx.

ST is set equal to the value of Vx.

Fx29 - LD F, Vx
Set I = location of sprite for digit Vx.

The value of I is set to the location for the hexadecimal sprite corresponding to the value of Vx. See section 2.4, Display, for more information on the Chip-8 hexadecimal font.

Fx33 - LD B, Vx
Store BCD representation of Vx in memory locations I, I+1, and I+2.

The interpreter takes the decimal value of Vx, and places the hundreds digit in memory at location in I, the tens digit at location I+1, and the ones digit at location I+2.

Developer: @SergioLuis
Reviewer: @mikelcaz
Integrator: @mikelcaz

Integrate the emulation core in the Android application.

The Android application must be aware of:

• Emulation core graphics memory
• Sound enablement and disablement.

The emulation core must be aware of:

• Keyboard keys pressing and releasing.

Developer: @SergioLuis
Reviewer: @mikelcaz

Please, look at the code: @jhvargas3112 @ugedo

Implement a first draft of the application so the development and testing of the application on Android devices can start.

This task is not to implement the final UI, but to implement a rudimentary version of it that can help us to launch the backend on Android, so the following functionalities are nice to have on this first UI:

• Be able of choosing a ROM to load to the backend.
• Start and stop ROM emulation.
• Display backend errors, if any.

Assigned people

Developer:
Reviewer:

Description

The splash screen font is affected by the user font size. It shouldn't, as the logo can become too big so easily, and has no sense to scale it that way to begin with.

Not every font should be scaled that way, so this should be fixed somehow, but only where makes sense.

Developer: @mikelcaz @SergioLuis
Reviewer: @SergioLuis
Integrator: @SergioLuis

Implement a custom Android View able of rendering the emulation core's graphic memory. Some thing to bear in mind:

• The onDraw() method of the view must be as fast as possible, or the application will start loosing frames (every render operation is done on the UI thread, and if that thread blocks for a while, the OS will warn the user that the application is unresponsive).
• Maybe we don't need to synchronize the access to the graphic memory. The already existing emulators have some flicker, which makes me think that the render happens more often than not in the middle of a DRW instruction. Maybe it is OK for simplicity and speed sake.

Assigned people

Developer: @SergioLuis
Reviewer: @mikelcaz

Description

Additional documentation here: http://devernay.free.fr/hacks/chip8/schip.txt

Developer: @jhvargas3112
Reviewer: @ugedo

Fill the Credits Wiki page. Find something nice to say about the team, our background, and maybe our links to LinkedIn / Twitter if necessary.

Developer: @jhvargas3112
Reviewer: @SergioLuis

Easy-peasy: just add the following lines at the end of the .travis.yml file located at the root of the repository:

notifications:
  webhooks: https://fathomless-fjord-24024.herokuapp.com/notify

Some tips:

• Create a new branch (task-010) starting from the head of dev.
• Make the necessary change and commit it.
• Push the branch to GitHub, and create a pull request to dev from GitHub.

If everything goes OK, we should receive a notification in out Telegram channel a few minutes after the pull request is created.

Assigned people

Developer:
Reviewer:

Description

The "save game" grid should be implemented as described in the the original design.

Related work

The UI design: #4

Dependencies:

• Game library grid interface #37
• Game saving and loading #38

To be extended with:

• Game previews: #44

Developer: @mikelcaz
Reviewer: @SergioLuis @jhvargas3112 @ugedo

Fill the Building and executing Wiki page. The work is not started.

Building should be really easy using Gradle, but bear in mind in the instructions the following:

• It is necessary to have the 1.8 JDK installed.
  • The JAVA_HOME environment variable should point to the JDK path.
• It is necessary to have the Android SDK installed, with the 27.? build tools.
  • The ANDROID_HOME environment variable should point to the SDK path.

The instructions should also cover how to install applications from outside the Play Store, and a link to the Releases section of the repository (we'll upload the APKs there).

We'll probably have DEBUG and RELEASE builds, so maintaining that Wiki page will be a work in progress until the end of the project, so feel free to delay this task as much as possible.

Assigned people

Developer:
Reviewer:

Description

The library that provided the animation was removed. That animation should be recovered, somehow...

Developers: @SergioLuis @mikelcaz
Reviewers: @ugedo @jhvargas3112

Implement a high-level backend (emulator) structure so the work on it can be divided. Bear in mind the following guidelines:

• Favor composition over inheritance.
• Rely on interfaces for composition!
• Split the code using packages.

Take this suggestion:

• The memory and the registers are simple concepts, but keeping them aside from the CPU should ease unit testing:
  • IMemory and IRegisters interfaces!
• The Clock needs to keep each instruction execution in sync with the necessary speed, but the unit tests don't need to run at the actual speed of the original system.
  • ÌClock interface!
• We should not need a complete CPU to test that the instructions actually work.
  • Static classes and methods to implement the instructions!
• The CPU needs the other components to work, but (probably) not the other way around.
  • Maybe we don't need a ICpu interface, but the CPU class will likely have a constructor that depends on IRegisters, IMemory and IClock.

Developer: @SergioLuis
Reviewers: @mikelcaz @ugedo @jhvargas3112

Implement a high-level application structure so the work on it can start to be divided. Bear in mind the following guidelines:

• The backend should constitute a project on its own.
  • In the future the backend could run on other platforms, so the backend SHOULD NOT have any dependencies to the Android framework.
• The backend should be covered with (lots of) unit tests, that must run with as little resources as possible.
  • The tests should constitute another project on their own.
  • We cannot depend on an Android Virtual Device to run unit tests on the backend.
• The Android application should only depend on the backend, and it should target Android 4.4 KitKat.

Assigned people

Developer: @mikelcaz
Reviewer: @SergioLuis

Description

This is what Mikel & Sergio agreed on, on thursday 5th of July, 2018. Adapt it as necessary, and add it to the Contributing wiki page:

# Branch naming / Issue labeling

* feature -> Something that the user is going to be able to use directly.
* hotfix -> Something that affects the expected behavior and it has been already released in a golden build.
* fix -> Something that affects the expected behavior, but it has not been released, or it has been shipped in an alpha/beta build channel.
* topic -> Everything else that does not fit the above categories.

Note: add the new section as a comment to this issue first. Then, once we both are happy with the changes, copy and paste it to the Wiki.

Assigned people

Developer:
Reviewer:

Description

Implement a way for the user to pause and resume the emulation.
Right now, the core supports the operation. This should be just a change in the Android application.

Developer: @SergioLuis
Reviewer: @mikelcaz
Integrator: @SergioLuis

Implement the following instructions:

00E0 - CLS
Clear the display.

00EE - RET
Return from a subroutine.

The interpreter sets the program counter to the address at the top of the stack, then subtracts 1 from the stack pointer.

1nnn - JP addr
Jump to location nnn.

The interpreter sets the program counter to nnn.

2nnn - CALL addr
Call subroutine at nnn.

The interpreter increments the stack pointer, then puts the current PC on the top of the stack. The PC is then set to nnn.

6xkk - LD Vx, byte
Set Vx = kk.

The interpreter puts the value kk into register Vx.

Ex9E - SKP Vx
Skip next instruction if key with the value of Vx is pressed.

Checks the keyboard, and if the key corresponding to the value of Vx is currently in the down position, PC is increased by 2.

ExA1 - SKNP Vx
Skip next instruction if key with the value of Vx is not pressed.

Checks the keyboard, and if the key corresponding to the value of Vx is currently in the up position, PC is increased by 2.

Fx0A - LD Vx, K
Wait for a key press, store the value of the key in Vx.

All execution stops until a key is pressed, then the value of that key is stored in Vx.

Assigned people

Developer:
Reviewer:

Description

On CHIP-8, the CPU speed is independent of the sound and delays speed.

• Usually, sound an delay timers goes at a rate of 60Hz.

• The CPU is usually much faster, on CHIPEIT (and many emulators before it) goes at 500 Hz by default.

Users should be able to select the speed they need or want. This can be implemented under the hood modifying the ClockDivisor frequencies (don't touch Clock or Chronometer directly).

Remarks:

• The delay timer independence is problematic, as can be used to many things in the game, so the program may be affected by timers in unexpected ways.

Challenges:

• Explaining users the sound/delay frequency seems complicated ("what on Earth is a 'delay timer', and what has to do with sounds?").

Developer: @mikelcaz
Reviewer: @SergioLuis
Integrator: @SergioLuis

Gradlew (gradle wrapper) files need the executable bit set on unix, as it should be. We are using (octal) 0755 on the other gradlew ones (chipeitlib/android), being console/gradlew the newcomer. As it was created on a Windows machine, we forget to verify it.

If we need more new executables, we should test them on unix systems first.

Assigned people

Developer:
Reviewer:

Description

In order to save/load a game state, is necessary to save/load the graphic memory. The API must be extended somehow to achieve that.

Note: This is a separate tasks from #38 because graphic memory serialization must be used for another tasks, such as taking snapshots of the screen in order to implement a nice game grid.

Related work

Precedes:
- #38 (use the same semantics).

Can be useful with:
- Preview #
- Snapshots #

Developer: @ugedo
Reviewer: @mikelcaz

Fill the License Wiki page. The work is not started. This should be really easy, remember that we use the GPLv3 license. Look for a template and fill it as necessary.