Thursday, September 15, 2022

Golang Cheat Sheet

Golang is a statically typed and compiled programming language designed at Google. Go plays a major role in Enterprises by developing highly scalable concurrent cloud computing systems like Docker + Kubernetes.

Let's check it out!

Installation
Download and install Go as per instructions for your target operating system. Afterwards verify go version.

Windows
Download and open the Go MSI file. Follow all prompts and ensure Go added to PATH environment variable.

Mac OS/X
Download and open the Go PKG file. Follow all prompts and ensure Go added to PATH environment variable.

Linux
Download and extract the Go archive. Launch Terminal and ensure Go added to PATH environment variable.
 sudo rm -rf /usr/local/go
 sudo tar -C /usr/local -xzf go1.18.3.linux-amd64.tar.gz
 export PATH=$PATH:/usr/local/go/bin/
 go version
Alternatively, include export PATH="$PATH:/usr/local/go/bin/" to your ~/.bashrc file for future use.

IMPORTANT
If Go does not install or update then you may have to remove snap package using sudo snap remove go. Also, verify Go environment variables by entering go env at the Terminal prompt for all operating systems.

Uninstall
Follow this guide on how to uninstall Go. While there seems to be many options, the following should work:
 sudo apt-get remove golang-go
 sudo apt-get remove --auto-remove golang-go

IDEs
Now we'd like to build Golang software so let's setup 2x main Integrated Development Environments IDEs:

VS Code
Visual Studio Code is a popular lightweight IDE available cross platform on Windows, Mac OS/X and Linux. Install VS Code and install the following plugins: Go, Go Doc, Go Outliner, Go Autotest + Go Test Explorer.
 Go  Rich Go language support for Visual Studio Code
 Go Doc  Show Go's documentation symbols and packages
 Go Outliner  Go code outline explorer and navigation package
 Go Autotest  Adds autotest functionality to vscode's Go mode
 Go Test Explorer  Go Test Explorer for unit and integration testing

Launch VS Code. Press Ctrl + Shift + P. Filter on "Go: Install". Choose "Go: Install/Update Tools". Select all. Ok. Also, if prompted "The "gopls" command is not available." bottom right then click Install to go get gopls.

Miscellaneous
Launch Terminal. Drag tab headings to prefer following order: Terminal, Problems, Output, Debug Console.

Mappings
If you are transitioning from Windows to Linux you may like to update keyboard mappings for example Back to Alt + LeftArrow. File | Preferences | Keyboard Shortcuts. Filter "Go Back". Click pencil. Hit Alt + LeftArrow.

Repeat process for Terminal: Copy Selection: File | Preferences | Keyboard Shortcuts. Hit Ctrl + C and Enter. Repeat process for Terminal: Paste into Active Terminal: File | Preferences | Keyboard Shortcuts. Hit Ctrl + V.

Navigation
If you are transitioning from Visual Studio on Windows to VS Code then the Solution Explorer with folders being represented as folder icons not arrows may be more familiar. Therefore, install vscode-icons plugin. Also, as code bases become larger it can be handier to install the Bookmarks plugin for easier navigation.

Shortcuts
 Ctrl + ,  Open Settings similar to Preferences  F5  Debug | Start w/ Debugging
 Ctrl + P  Search files to open e.g. main.go  Ctrl + F5  Debug | Run w/o Debugger
 Ctrl + R  Select to open from previous files  F9  Debug | Toggle Breakpoint
 Ctrl + Shift + O  Outline file structure for opened file  F10  Debug | Step Over
 F12  Navigate | Go to Definition  F11  Debug | Step Into
 Alt + Left  Navigate | Going Backward  Shift + F11  Debug | Step Out

Zoom In
Finally, you may like to Ctrl + "+" to zoom in on the Explorer and Terminal then reduce the Font Size to 12.


GoLand
GoLand is a cross-platform Go Integrated Development Environment IDE on Windows, Mac OS/X and Linux. Install GoLand and setup the following configurations as commercial alternative with better IDE Intellisense.

Configurations
Launch GoLand. In the "Welcome to GoLand" popup choose Customize | Color theme | IntelliJ Light. Next, choose All settings... Expand Go tab at the top | GOROOT | Add SDK... Local | Navigate to where Go was installed previously e.g. /usr/local/go. Finally update GOPATH. Click "+" select ~/go. OK | Apply | OK.


IMPORTANT
Verify GOROOT path is correct from Terminal via go env | grep GOROOT. Repeat for go env | grep GOPATH. Also, in Go tab | Go Modules ensure "Enable Go modules integration" is checked as may not be by default.


Mappings
Align GoLand Keymap to VS Code Keymap for consistent keyboard shortcuts and developer IDE experience. In the "Welcome to GoLand" popup choose Plugins | VSCode Keymap | Install. Navigate back to Customize. Under Keymap change the default value to VSCode. Now all VS Code shortcuts above will work in GoLand.

Additionally to Ctrl + Shift + O, outline file structure for opened file, GoLand has these handy shortcuts also:
 Ctrl + Numpad -  Collapse struct types for easier overall type visibility in IDE
 Ctrl + Numpad +  Expand struct types to navigate type properties + methods

NOTE
If Ctrl + Shift + O launches Symbols then remove duplicate: Choose Settings | Keymap | filter as "symbol". Double click Navigate | Go to Symbol | Edit | Remove Ctrl+Shift+O | Apply | OK. Repeat this as necessary.

Settings
Finally, from Customize | All settings... here are some more general GoLand IDE settings that can be useful:
 Editor | General | Code Folding | Fold by default | General  UNCHEKED
 Editor | Font  JetBrains Mono | Size: 14.0 | Line: 1.2
 Editor | Color Scheme Font  Scheme: Classic Light
 Editor | Inspections | Proofreading | Typo  UNCHEKED

Example
Create the obligatory Hello World program in both VS Code and GoLand IDE to complete the configration:

main.go
package main
import "fmt"

func main() {
	fmt.Println("Hello World!")
}

VS Code
Create "HelloVSCode" folder at ~/go/src. Launch VS Code. Open folder [Ctrl+K, Ctrl+O] HelloVSCode folder. New File | main.go. Enter + save Hello World source code from package main above. Launch new Terminal:
go mod init HelloVSCode
go mod tidy

go build .
go run .
Set breakpoint in main.go. Run menu and choose either Start Debugging or Run without Debugging option.


GoLand
Launch GoLand. New Project | Enter Location and GOROOT as above i.e. Go 1.18.3 /usr/local/go. Create.

 Location  ~/go/src/HelloGoLand
 GOROOT  Go 1.18.3 /usr/local/go
 Enable vendoring support automatically  CHECKED

In main.go right click triangle next to func main() | Modify Run configuration... Ensure there are no errors. If there are errors then ensure if Run kind is Package the package name matches in go.mod. Otherwise choose File | main.go. Once confirmed no errors then right click triangle and choose the Run or Debug configuration.

Cache
If GoLand complains "cannot resolve symbol" then choose File | Invalidate Caches... | Invalidate and Restart.

Configurations
Track active item in solution explorer similar to Visual Studio: Click cog to right of Project and Always Select Opened File. Hit shift key twice for quick search. Remember Rename files and folder is in the Refactor menu!

Layout
It may be good idea to position Problems tab next to code window so you can see issues as you enter code. In GoLand, click cog on Problems | Move to | Right Top. In VS Code right click Problems | Move Panel Right.

Navigation
As code bases become larger use the Bookmarks feature for easier navigation. Right click the code gutter + Add Bookmark. View menu | Tool Windows | Bookmarks. This can also be used to edit/remove Breakpoints.

Source Control
In GoLand, by default the Staging area may be disabled. Therefore, you wouldn't see any Unversioned files To disable changelists choose File menu | Settings | Version Control | Git | Enable staging area | UNCHECK.

In GoLand, top right under Project is the Control tab. Right click any file and choose Rollback to revert any changes. In VS Code the Source Control tab is third tab. Choose Discard Changes as corresponding action.


Summary
To summarize, we have a simple setup for Golang programming on Windows, Mac OS/X and Linux. There is much to explore e.g. Cloud Computing and developing highly scalable concurrent applications using Golang!
This will be topic of the next post.

Wednesday, August 31, 2022

Linux Setup Cheat Sheet III

In the previous post, we set up Ubuntu Linux on Windows and Mac OS/X using VirtualBox. Now we focus our set up on dedicated Ubuntu Linux workstation or Windows PC that has dual boot with Ubuntu Linux installed.

Let's check it out!

Account
Typically, during the installation process, an admin account is prompted to be created with username and password. However, follow these instructions to add new user account with admin access on Ubuntu Linux.
 adduser stevepro
 usermod -aG sudo stevepro
 id stevepro
 su - stevepro

Alternatively, manage user accounts from Settings | Users user interface to add new user account. Initially, the account user will use the default icon. Consider changing via Settings | Users | Picture | Select File.

Login
If, whenever you attempt to login, you get the Ubuntu black screen with flashing cursor then attempt this fix: Reboot computer and login as recovery mode. Once logged in again, download and install NVIDIA.run.

Checkout here and here how to install nVidia driver on Ubuntu Linux e.g. NVIDIA-Linux-x86_64-460.84.run
 sudo su
 cd Downloads
 ./NVIDIA.run

IMPORTANT
If you are running X server then you may get an error when trying to install NVIDIA.run while still logged in:
 Ensure you are logged out!
 sudo service lightdm stop
 sudo init 3
 ./NVIDIA...run
 sudo service lightdm start

In, Software Updater | Additional Drivers, ensure NVidia is set "Using X.Org X server" as alternative driver.


Graphics
Initially, video file formats like mp4 may result in black screen. If so then install all the Multimedia Codecs:
 sudo apt-get update
 sudo apt install ubuntu-restricted-extras

Ubuntu
Confirm the version of Ubuntu Linux installed on terminal with lsb_release -a. Upgrade now accordingly:
 sudo apt update && sudo apt upgrade
 sudo reboot command
 sudo apt install update-manager-core
 sudo do-release-upgrade
 sudo reboot
 lsb_release -a

Kernel
Mainline is graphical tool to install the latest mainline kernel in Ubuntu Linux. Install Mainline from Terminal:
 sudo add-apt-repository ppa:cappelikan/ppa
 sudo apt update
 sudo apt install mainline
 mainline --check
 mainline --list
Start | Ubuntu Mainline. From the User Interface now install / uninstall Ubuntu Linux versions seemlessly. Once Ubuntu Linux kernel has been updated confirm kernel new version with uname -r.

Diff Tools
On Windows PC, Tortoise Merge is handy tool to compare 2x files whereas WinMerge is handy tool that can compare 2x directories. Meld + KDiff3 are alternatives for Linux both installed from Ubuntu Software Center.

Meld
File | New Comparison. File comparison navigate to file 1. Directory comparison navigate to file 2. Compare.

KDiff3
Similar to WinMerge: A. Directory navigate to directory 1. B. Directory navigate to directory 2. Compare OK.

Disk Space
Use Ubuntu Linux Disk Analyzer utility to identify common locations which can be used to free up disk space:
 rm -rf ~/.local/share/Trash/*
 du -sh ~/.cache/thumbnails
 sudo du -h /var/lib/snapd/snaps
 sudo du -sh /var/cache/apt
 sudo apt-get autoclean
 sudo apt-get clean
 sudo journalctl --disk-usage
 sudo journalctl --vacuum-time=3d
Other utilities to identify excess storage include ncud and bleachbit both which can be sudo apt install[ed].

Find
Here are some simple but effective uses of the find command e.g. find all text in file that follows predicate:
 find -L . -type f -exec grep -HniI 'g++' {} \; > ~/Steven/gpp.txt

Another useful example is how to find all of the distinct file extensions in a particular folder hierarchy:
 find . -type f | perl -ne 'print $1 if m/\.([^.\/]+)$/' | sort -u

Shortcuts
 General  Minimize all windows  Ctrl + Alt + D
 gedit  Move prev tab  Ctrl + Alt + PgUp
 gedit  Move next tab  Ctrl + Alt + PgDown

SSH
Secure SHell [SSH] may not be enabled after Ubuntu Linux is installed. Therefore you may get the following:
 ssh stevepro@192.168.15.50
 ssh: connect to host 192.168.15.50 port 22: Connection refused

Server
Here is how to fix the Connection refused issue on port 22. On the destination server set up the following:
 # Make sure OpenSSH is installed
 # Install SSH
 # Check SSH service
 # Start SSH service
 sudo apt list --installed | grep openssh-server
 sudo apt install openssh-server
 sudo service ssh status
 sudo service ssh start

Client
On source client connect to Files | Other Locations | Connect to Server sftp://stevepro@192.168.15.50.
Also, ssh stevepro@192.168.15.50 should now work!

Mouse Scroll
After setting up new blue tooth mouse the default scroll was too slow. Therefore, install and set up lmwheel:
 sudo apt-get install imwheel

Create mouse.sh. Integrate the following shell script. Set execute permissions. Configure using ./mouse.sh.
#!/bin/bash
if [ ! -f ~/.imwheelrc ]
then
cat >~/.imwheelrc<<EOF
".*"
None,      Up,   Button4, 1
None,      Down, Button5, 1
Control_L, Up,   Control_L|Button4
Control_L, Down, Control_L|Button5
Shift_L,   Up,   Shift_L|Button4
Shift_L,   Down, Shift_L|Button5
EOF
fi
CURRENT_VALUE=$(awk -F 'Button4,' '{print $2}' ~/.imwheelrc)
NEW_VALUE=$(zenity --scale --window-icon=info --ok-label=Apply --title="Wheelies" --text "Mouse wheel speed:" --min-value=1 --max-value=100 --value="$CURRENT_VALUE" --step 1)
if [ "$NEW_VALUE" == "" ];
then exit 0
fi
sed -i "s/\($TARGET_KEY *Button4, *\).*/\1$NEW_VALUE/" ~/.imwheelrc # find the string Button4, and write new value.
sed -i "s/\($TARGET_KEY *Button5, *\).*/\1$NEW_VALUE/" ~/.imwheelrc # find the string Button5, and write new value.
cat ~/.imwheelrc
imwheel -kill

VNC Viewer
If you are transitioning from Windows to Linux you may like to remote desktop from Windows to Linux box.

Linux
Follow all instructions. Change Ubuntu desktop manager from GNOME to LightDM. Install X11VNC as service on Ubuntu. Launch Terminal and enter the following. When prompted, ensure you choose lightdm not gdm3:
sudo apt-get update
sudo apt-get install lightdm
sudo reboot
sudo apt-get install x11vnc

After installing LightDM, rebooting and installing X11VNC, configure x11vnc.service. Replace your password!
sudo gedit /lib/systemd/system/x11vnc.service

[Unit]
Description=x11vnc service
After=display-manager.service network.target syslog.target

[Service]
Type=simple
ExecStart=/usr/bin/x11vnc -forever -display :0 -auth guess -passwd REPLACE_WITH_YOUR_LOGIN_PASSWORD
ExecStop=/usr/bin/killall x11vnc
Restart=on-failure

[Install]
WantedBy=multi-user.target

Finally, after configuring x11vnc.service, enter the following commands to complete the VNC Viewer setup.
systemctl daemon-reload
systemctl enable x11vnc.service
systemctl start x11vnc.service

systemctl status x11vnc.service
ip addr | grep 192                        # NOTE the IP address 192.168.1.X

IMPORTANT
Don't lock the screen as you won't be able to VNC back in! Change Settings | Privacy | Screen Lock to this:
Windows
Download and install VNC Viewer. Launch VNC Viewer. Setup Team. Choose File | New Connection. Enter the IP address from above on port 5000 for VNC Server e.g. 192.168.1.X:5900. Enter friendly name + Connect.

When prompted choose Continue. Enter password | Check Remember password. Unfortunately not all keys may work e.g. Caps Lock. Also, you may have to disable and re-enable Repeat Keys from Universal Access.

Summary
Now we have a dedicated Ubuntu Linux workstation set up we are all set for cloud computing development!

Thursday, August 4, 2022

Skazka Code Complete

Skazka is a Slavic RGP Adventure game originally written in BASIC for Sega SC-3000 and posted to SC-3000 Survivors Facebook group. The source code is now ported to C using devkitSMS for the Sega Master System.

Let's check it out!

Note: Skazka development based on devkitSMS Programming Setup and devkitSMS Programming Sample.
Download source code here.


Instructions
Skazka captures the core mechanics of old school RPG experience: Kill monsters | level up | upgrade gear. There are 5x different enemies in increasing order: Razboynik, Hungry Wolf, Kikimora, Leshy, Baby Yaga. Defeat final boss Koschey to beat the game!

Tools
Here are a list of Tools and frameworks that were used in the development of this project:
 KEY  VALUE
 Programming  devkitSMS
 Compiler  sdcc 3.6.9
 Assembler  WLA-DX
 IDE  Visual Studio 2015 / Visual Studio Code
 Languages  C / Z80
 Graphics  BMP2Tile 0.43 / BMP Converter / GIMP 2
 Music  pcmenc / vgm2psg
 Emulators  Emulicious / Fusion / Meka
 Debugger  Emulicious Debugger

ROM Hacking
You can hack this ROM! Download and dump Skazka into Hex Editor, e.g. HxD, and modify bytes:
 ADDRESS  VARIABLE  DESCRIPTION
 0x019E  Delay  Used to speed through any game delay.
 0x019F  Invincible  Non-zero value enables invincibility.
 0x01A0  Current XP  Non-zero sets current experience pts.
 0x01A1  Current HP  Non-zero sets default healthy points.
 0x01A2  Set Gold  Non-zero sets current gold available.
 0x01A3  Set Weapon  Set value to 1 or 2 for stock else 0.
 0x01A4  Set Armor  Set value to 1 or 2 for armor else 0.
 0x01A5  Add Life  Set value to 1=Life otherwise 0=None.
 0x01A6  Village Talk  Set value to 1=repeat villagers talk.
 0x01A7  Music Off  Set 0=Music to play otherwise silent.
 0x01A8  Sound Off  Set 0=Sound to play otherwise silent.

Hints
  • Try to buy weapon "Sword" or armor "Tegilay" with your initial gold before entering any forest fights.
  • After completing each forest fight, ensure you "Rest" at the main screen to replenish all health points.
  • In the shop when you buy items you already have then will be deducted unconditionally so be aware!
  • Get "+1 Life" just in case you lose a fight or the final boss battle so you do not have to restart game.
  • Maximize HP + XP + get the best weapon "Axe" and best armor "Kolchuga" before fighting the boss.
  • Fight boss when you have > 60 XP because your weapon and armor may be slightly more powerful!

Cheats
  • On title screen, hold fire2 to skip intro music. Same applies on boss and over screens.
  • On title screen, hold fire2 after intro music completes to reveal hidden credits screen.
  • On stats screen, move joystick left or right to skip over the flashing arrows indication.
  • In Easy mode forest screen, press fire2 to "Run away" without risking losing any HPs.

Debugging
  • On Windows you can debug the source code directly from in Visual Studio Code after pressing F5.
  • On Linux you can debug source code directly from Visual Studio Code but launch Emulicious first.

Credits
Extra special thanks to sverx for the devkitSMS. Plus StevePro Studios would like to thank Calindro all for his 24/7 Tech Support. Plus shout out to Mojon Twins na_th_an in which I found lots of some cool sound effects.

Update
Skazka V1.0 was initially a text-based RPG adventure game. However, after collaboration with Kagesan from SMS Power!, graphics were added for all screens for V2.0 which is the most up-to-date version of the game.



Summary
Despite the fact that Skazka was a simple text-based RPG adventure with limited game play, the cool aspect was collaborating with original developer and working together to port the game to the Sega Master System.

Skazka was entered in the SMS Power! 2022 competition to connect the Sega SC-3000 Facebook group and the SMS Power! community with the goal to spread Sega 8-bit preservation and fanaticism. That's awesome!

Monday, July 4, 2022

devkitSMS Programming Sample V

In the previous post, we checked out devkitSMS Programming Setup II. The devkitSMS provides tools and code to support many homebrew development projects for the Sega Master System and Sega Game Gear.

The latest version of the devkitSMS requires an updated version of Small Device Cross Compiler SDCC 4.x and supports new and updated features including the ability to page both code and content transparently.

Let's check it out!

Software
Follow all instructions from the previous post: this documents how to setup the pre-requisite software.
Note: ensure you have downloaded and installed the devkitSMS and Small Device C Compiler [SDCC].

Also ensure that pcmenc is installed in the SDCC bin folder as this utility is used to play WAV audio files.

Demo
All demos in this devkitSMS programming sample are based on the simple Hello World program the previous post that utilizes Visual Studio 2015 on Windows but can be deployed cross platform on Windows and Linux.

Create folder C:\DevkitExample. Create the following sub-folders: crt0, dev, lib, tmp. Note: all content now preferred to reside under content sub-folder beneath the main dev folder. All content also built using scripts.


Development
Launch Visual Studio 2015. File | New | Project... | Visual C++ | Win32 | Win32 Project

 Name:  Game
 Location:  C:\DevkitExample\dev
 Create directory for solution  UNCHECKED
OK

 Application type:  Console application
 Additional options:  Empty project CHECKED
Finish

Ensure Visual Studio 2015 is configured as per instructions here to automate build process from Ctrl+1 hot key. Create folders beneath dev for .vscode and devkit. Import all code from here including build the scripts.

main.c
#include "main.h"
void main( void )
{
  devkit_SMS_init();
  devkit_SMS_setSpritePaletteColor( 0, devkit_RGB( 3, 3, 3 ) );
  devkit_SMS_displayOn();
  for( ;; )
  {
    devkit_SMS_waitForVBlank();
  }
}

Graphics
Follow all instructions from the previous post to download and install BMP2Tile utility to convert graphics into Sega Master System format. Download new gfxcomp_stm.dll STM compressed format to output directory.

Splash
Here is an example of background tiles that will exhaust the full 256 x 192 resolution e.g. the Splash screen:

Follow the same settings as per here but this time use this script to automate the corresponding formatting:

build.bat
bmp2tile.exe raw/splash.bmp ^
  -savetiles "splash (tiles).psgcompr" -removedupes -nomirror -planar -tileoffset 128 ^
  -savetilemap "splash (tilemap).stmcompr" ^
  -savepalette "splash (palette).bin" ^
  -fullpalette -exit

 Tiles:  Remove duplicates  Checked
 Tiles:  Planar tile output  Checked
 Tilemap:  Use sprite palette  Unchecked
 Tilemap:  In front of sprites  Unchecked
 Palette:  Output hex (SMS)  Checked

Opaque
Candy Kid, which is a Pacman clone, uses opaque background tiles to obscure the main sprite as he goes thru the exits. This technique renders a white 16x16 tile but uses sprite palette bitwise OR with tile priority.

tile_manager.c
static void draw_tile_priority( unsigned char offset, unsigned char x, unsigned char y )
{
  unsigned int priority = devkit_TILE_PRIORITY() | devkit_TILE_USE_SPRITE_PALETTE();

  devkit_SMS_setNextTileatXY( x + 0, y + 0 );
  devkit_SMS_setTile( ( *game_tiles__tilemap__bin + offset + 0 ) | priority );
}

IMPORTANT: the sprite palette color in this example must be black to match background despite white tiles.

Tools
In previous years, Gimp was used to convert graphics as Indexed [16] mode to meet the 4bpp Sega Master System compatible requirements. However, paint.net is great to output PNG files for BMP online converter:
 Color:  4 (indexed)
 With rows direction:  Bottom - Top (default)
 Quantization equal to:  8
 Using dithering:  No


Scrolling
Scrolling in video games involves moving graphics across a display, either horizontally and/or vertically such that the layout does not change but rather moves the view across as an image larger than the whole screen.

Horizontal scrolling was very popular for action, run-and-gun and shoot/beat 'em up games whereas vertical scrolling was used in top down shooters. The devkitSMS tutorial has both vertical and horizontal examples:

Horizontal
Here is the devkitSMS tutorial horizontal scrolling "Ice Hockey" example using the SMS_loadTileMap() API.


scroll_manager.c
void engine_scroll_manager_update_right( unsigned char delta )
{
  unsigned char *src = NULL;
  unsigned char ytile = 0;
  unsigned int index = 0;
  const unsigned int size = 2;

  unsigned int x = 0;
  unsigned char y = 0;

  if( scrollRightDivided8 < scrollWidth )
  {
    scroll -= delta;
    scrollRight += delta;
    scrollRightDivided8 = scrollRight / 8;
    devkit_SMS_setBGScrollX( scroll );

    if( ( scrollRight % 8 ) == delta )
    {
      for( ytile = 1; ytile < Y_TILE_MAX; ytile++ )
      {
        x = X_TILE_MAX + scrollRightDivided8;
        y = ytile - 1;
        index = ( ( BG_TILE_WIDTH*ytile ) + ( X_TILE_MAX + scrollRightDivided8 ) ) * 2;
        src = ( void * ) &hockey__tilemap__bin[ index ];
        devkit_SMS_loadTileMap( x, y, src, size );
      }
    }
  }
}

Vertical
Here is the devkitSMS tutorial vertical scrolling "Marilyn" [MM] example using the SMS_loadTileMap() API.


scroll_manager.c
void engine_scroll_manager_down()
{
  struct_scroll_object *so = &global_scroll_object;
  unsigned int index;
  unsigned int y;

  if( so->scroll < so->height )
  {
    so->scroll++;
    devkit_SMS_setBGScrollY( so->scroll );

    if( ( so->scroll % 8 ) == 0 )
    {
      y = ( 24 + ( so->scroll / 8 ) ) % 28;
      index = ( 24 + ( so->scroll / 8 ) ) * 32 * 2;
      devkit_SMS_loadTileMap( 0, y, ( void * ) &MM__tilemap__bin[ index ], so->size );
    }
  }
}

Vertical II
Here is another vertical scrolling example which prefers SMS_setNextTileatXY() after loading all the tiles.


map_manager.c
static void draw_map_row()
{
  struct_map_object *map_data = &global_map_object;
  unsigned char i, j;
  unsigned char y;
  unsigned char *map_char;
  unsigned int base_tile, tile;
  unsigned char buffer[ 16 ];

  decompress_map_row( buffer );
  for( i = 2, y = map_data->background_y, base_tile = 256; i; i--, y++, base_tile++ )
  {
    devkit_SMS_setNextTileatXY( 0, y );
    for( j = 16, map_char = buffer; j; j--, map_char++ )
    {
      tile = base_tile + ( *map_char << 2 );
      devkit_SMS_setTile( tile );
      devkit_SMS_setTile( tile + 2 );
    }
  }
}

PCM Samples
The Sega Master System is able to play high quality Pulse-Code Modulation [PCM] samples with the pcmenc tool built by Maxim from the SMS Power! community which means WAV files can be converted and played.

Single Bank
Ensure the pcmenc executable currently lives in ~/SDCC/bin folder and accessible from $PATH. Launch the terminal and execute the following command to convert an input "test" WAV file to pcmenc compatible file:
 if exist "SoundFx.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 SoundFx.wav

This assumes that the converted WAV file will be less than 16KB; the maximum size for Sega Master System bank. If not then the WAV file will need to be converted to multiple WAV files + converted [example below].

Here is an example of converting an input WAV file using pcmenc to be SMS compatible for code integration.
Contains the engine code to init and play the converted WAV file as PCM sample on the Sega Master System.

sample_manager.c
void engine_sample_manager_init( const void *psginit );
void engine_sample_manager_play( const void *sample );

riff_manager.c
Public API that game code will call as wrapper around the sample manager to actually play the PCM sample.

IMPORTANT:
I've found that is usually safest to init the riff manager before playing each riff to avoid unwanted noise!

Multiple Banks
When the converted WAV file is greater than 16KB then use Audacity to convert the riff to multiple WAV files. Download, install and launch Audacity. Open WAV file. Divide into multiple smaller files using these settings:

 Project Rate (Hz)  44100
 Snap To  Off
 Selection Start  000,000,000 samples
 Length CHECKED  000,050,000 samples
 Audio Position  000,000,000 samples

Hit Ctrl+B | Enter "01". Repeat as per number of banks required at 50,000 samples intervals for example:
 Riff 01  Selection Start  000,000,000 samples  Length CHECKED  000,050,000 samples
 Riff 02  Selection Start  000,050,000 samples  Length CHECKED  000,050,000 samples
 Riff 03  Selection Start  000,100,000 samples  Length CHECKED  000,050,000 samples
 Riff 04  Selection Start  000,150,000 samples  Length CHECKED  000,050,000 samples

File menu | Export Multiple. Choose export location | Export | OK. Execute the following script to convert:
if exist "01.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 01.wav
if exist "02.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 02.wav
if exist "03.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 03.wav
if exist "04.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 04.wav

Finally, rename the *.wav.pcmenc files to more code friendly names and copy the files to parent banks folder with each *.wav.pcmenc file in its own bank. Use this utiltiy to automate this task and generate the scripts.

Invoke the riff manager similar to single bank example except iterate thru all banks that are required to play riff. The only current drawback with this technique is the main thread blocks as the riff plays synchronously!


Banked Code
SDCC 4.x supports banked code which means it is now possible to page in and out code in a transparent manner. The banked code should be written in separate source files that get allocated in separate code banks. To summarize, banked code means that total code will not be restricted to 32KB maximum size.


Method
1. Put all banked code in separate source files marking banked functions using __banked SDCC keyword.
 banked_code_1.h  banked_code_1.c
 #ifndef _BANK_1_H_
 #define _BANK_1_H_

 int banked_code_1() __banked;

 #endif//_BANK_1_H_
 #include "banked_code_1.h"

 int banked_code_1() __banked
 {
 	return 1;
 }

2. Compile each banked code source file into a specific separate code segment as part of the build script.
 sdcc --debug -c -mz80 --codeseg BANK1 banked_code_1.c
 sdcc --debug -c -mz80 --codeseg BANK2 banked_code_2.c
 sdcc --debug -c -mz80 --codeseg BANK3 banked_code_3.c

3. Use the newly provided crt0b_sms.rel as the first module into your linker call instead of crt0_sms.rel.
4. Instruct the linker to place the banked code at address 0x4000 + the virtual address of the bank which will be calculated as bank number * 2^16 i.e. code segment BANK1 at 0x14000, BANK2 at 0x24000 etc.
 sdcc --debug -o output.ihx -mz80 --no-std-crt0 --data-loc 0xC000 \
 -Wl-b_BANK1=0x14000 \
 -Wl-b_BANK2=0x24000 \
 -Wl-b_BANK3=0x34000 \
 ../crt0/crt0b_sms.rel \
 ../lib/SMSlib.lib \
 main.rel \
 banks/banked_code_1.rel \
 banks/banked_code_2.rel \
 banks/banked_code_3.rel \

5. Finally use the new makesms tool to convert the ihx output to sms format instead of the ihx2sms tool.
 makesms output.ihx output.sms


Summary
Armed with all this knowledge, we are now in an excellent position to upgrade any existing game projects for Sega Master System to latest version of devkitSMS on SDCC 4.x built cross platform for Windows and Linux!

Saturday, June 4, 2022

devkitSMS Programming Setup II

In 2017, we checked out devkitSMS Programming Setup to build 8-bit video games in C for the Sega Master System (SMS). Here we use SDCC v3.6.9 which allows maximum 32KB for your main ROM game code size.

Now, the latest devkitSMS requires SDCC 4.x which supports banked code which means it is now possible to page code out transparently. Plus we'd also like to build SMS projects cross platform for Windows and Linux.


Let’s check it out!

devkitSMS
The devkitSMS is a collection of tools and code built specifically for the Sega Master System but also supports homebrew development using C language for SG-1000, SC-3000 and the Sega Game Gear.

Software
Follow all instructions from the previous post: this documents how to setup the pre-requisite software.

Here is a summary of all required software to be installed:
 Name Version
 C IDE Editor Visual Studio 2015
 C IDE Editor Visual Studio Code
 Cross compiler Small Device C Compiler
 
 Name Version
 Make files Cygwin
 Emulators Emulicious, Fusion, Meka
 Debugger Emulicious Debugger
Note: Emulicioushas dependency on Java therefore launch using java -jar ~/Sega/Emulicious/Emulicious.jar

Windows
Download and install sdcc-4.1.0-x64-setup.exe to C:\Program Files\SDCC. Choose all features to install.


There should be no extra configuration except add C:\Program Files\SDCC\bin to the Environment PATH.


Start | Run | cmd. Type sdcc --version. The following info should display to confirm SDCC version 4.1.0:


Linux
Download and extract sdcc-4.1.0-amd64-unknown-linux2.5.tar.bz2 to ~/sdcc. This should install all features.


There should be no extra configuration except add $HOME/sdcc/bin to the ~/.bashrc file so always available.
 gedit ~/.bashrc
 export PATH="$PATH:$HOME/sdcc/bin"

Launch Terminal. Type sdcc --version [sdcc -v]. The following should display to confirm SDCC version 4.1.0:


Directories
 Windows  C:\Program Files\SDCC\bin
 Linux  ~/sdcc/bin

devkitSMS
Navigate to the devkitSMS repository on github. @sverx has full instructions here and advises to copy the following 4x executables into SDCC bin folder: assets2banks.exe, folder2c.exe, ihx2sms.exe, makesms.exe.
# Clone devkitSMS
git clone https://github.com/sverx/devkitSMS.git

# Copy 4x files
cd devkitSMS
copy assets2banks/%PLATFORM%/assets2banks %INSTALLATION%/SDCC/bin
copy folder2c/%PLATFORM%/folder2c.exe %INSTALLATION%/SDCC/bin
copy ihx2sms/%PLATFORM%/ihx2sms.exe %INSTALLATION%/SDCC/bin
copy makesms/%PLATFORM%/makesms.exe %INSTALLATION%/SDCC/bin

Note: my preference is to usually copy the relevant files up-to-date as each Master System project is built.

Example
As an example, replicate the simple program from 2017 that sets the border colors of the screen using devkitSMS but this time we will port the Windows build cross platform to Linux and include debugging!

Create new directory HelloWorld: ~/HelloWorld. Copy these files across crt0_sms.rel, SMSlib.h, SMSlib.lib. Launch Visual Studio Code. Open HelloWorld directory. Create new file main.c and enter the following code:

main.c
#include "SMSlib.h"
void main ( void )
{
  SMS_setSpritePaletteColor( 0, RGB( 3, 3, 3 ) );
  SMS_displayOn();
  for ( ;; )
  {
    SMS_waitForVBlank();
  }
}

SMS_EMBED_SEGA_ROM_HEADER(9999, 0);
SMS_EMBED_SDSC_HEADER(1, 0, 2017, 9, 15, "StevePro Studios", "Hello World", "Simple Sega Master System demo to run on real hardware!");

Build
Manually compile, link and execute the Hello program. Launch command prompt: Start | Run | cmd.


Change directory cd ~/HelloWorld. Next, execute following 3x commands (in bold) but add debug keyword:
 ACTION  COMMAND  OUTPUT
 Compile   sdcc --debug -c -mz80 main.c  main.rel
 Link  sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel
 main.rel SMSlib.lib
 output.ihx
 Exceute  ihx2sms output.ihx output.sms  output.sms 

Finally, type java -jar ~/Sega/Emulicious/Emulicious.jar output.sms to launch the Hello program.
Congratulations! You have just written your first SMS program using devkitSMS.


Automate
Let's automate the build process: create build script file that contains the previous commands. On Windows name the file build.bat. On Linux name the file build.sh and add EXE permissions as chmod +x build.sh.
@echo off
sdcc --debug -c -mz80 main.c
sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel main.rel SMSlib.lib
ihx2sms output.ihx output.sms
java -jar ~/Sega/Emulicious/Emulicious.jar output.sms

Visual Studio Code
Finally, add hidden .vscode folder in Visual Studio Code + include tasks.json and launch.json files beneath:

tasks.json
{
    "version": "2.0.0",
    "label": "build",
    "type": "shell",
    "linux": {
        "command": "./build.sh"
    },
    "windows": {
        "command": "./build.bat"
      },
    "presentation": {"echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": false, "clear": true},
    "group": {"kind": "build", "isDefault": true},
}
Important: On Windows prefer the ./build syntax as Linux otherwise an "unrecognized cmdlet" may result.

launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/output.sms",
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}
On Linux, launch Emulicious as above. Press Ctrl + Shift + B to build code and F5 to debug step thru code:


Visual Studio 2015
For completeness, if the main workstation is Windows then another option is Visual Studio 2015 can also be used to debug step thru the ANSI-C source code. For more background info see this. Here is the alternative:

main.c
#include "main.h"
void main( void )
{
  devkit_SMS_init();
  devkit_SMS_setSpritePaletteColor( 0, devkit_RGB( 3, 3, 3 ) );
  devkit_SMS_displayOn();
  for( ;; )
  {
    devkit_SMS_waitForVBlank();
  }
}

Summary
To summarize, the Sega Master System development process has been very consistent after the SDCC 4.x upgrade plus the ability to support banked code means initial 32KB ROM restriction now no longer applies!
This will be the topic of the next post.

Saturday, January 1, 2022

Retrospective XIII

Last year, I conducted a simple retrospective for 2020. Therefore, here is a retrospective for 2021.

2021 Achievements
  • Setup Z80 Assembly Programming cross platform for Windows, MacOS/X and Linux
  • Configure VS Code Emulicious Debugger plugin for Z80 source code stepin + hacks
  • Enter Van Halen demo for SMS Power! 2021 competition built in pure Z80 Assembly
  • Build Van Halen quiz using C/SGDK for the Sega MegaDrive similar to C/devkitSMS
  • Upgrade Simpsons Trivia for Sega Master System include more characters and SFX
  • Port Simpsons Trivia to the Sega MegaDrive using similar C development processes
  • Compile Docker cheat sheet for cluster containerization in Cloud Native technology
  • Compile Kuberenetes cheat sheet for Cloud Native technology cluster orchestration
Note: port low level homebrew games built from C/devkitSMS to C/SGDK is an achievement!

2022 Objectives
  • Configure VS Code Emulicious Debugger plugin for C/devkitSMS source code step thru
  • Transition homebrew programming skills in C to professional work for example in CGo
  • Expand low level cross platform skills to Linux kernel e.g. eBPF networking + security
  • Extend Golang into Docker / Kubernetes experience as Cloud Native technology work

Cloud Cloud Computing is the on-demand delivery of infrastructure [hardware / servers], storage + databases via the Internet frequently delivered by cloud-based platforms: Amazon AWS / Google GCP / Microsoft Azure.

Cloud Native is architecture for assembling these cloud-based components optimized for cloud environment; Not about servers but the services. Enterprises modernize their infrastructure and process by choosing cloud technologies e.g. Docker for containerization, Kuberenetes for orchestration, that best fit their specific needs.

Golang Golang [Go] is statically typed programming language syntactically similar to C but with memory safety and garbage collection. Go was developed at Google to help solve the problem of concurrent messaging between distributed systems in the cloud using CSP style concurrency. Subsequently, Go is asynchronous by default.

Therefore, all three major public cloud providers AWS, GCP, Azure support Go and have SDKs that interface with their systems in Go. Thus Go may become the standard way of distributed computing into the future.

Cgo
CGo is a technology which allows Go programs to interoperate with C libraries. For example distributed cloud computing packages that consume ModSecurity C/C++ library for Web Applicaton Firewall (WAF) detection.

Another example eBPF: a revolutionary technology that can run sandboxed C programs safely and efficiently extending the capabilities of the Linux kernel, without requiring changes to kernel source code or load kernel modules, consumed from Go packages providing high-performance networking in cloud native environments.

Summary
Writing low level C code to target 8-bit Sega Master System hardware and now the 16-bit Sega Mega Drive it has proved to be very valuable experience for CGo applications which could assist in Go + Cloud Computing. The next challenge is port projects exclusively on Windows and include Linux system builds cross platform J

Monday, November 15, 2021

Vintage Van Halen Code Complete

There's only one way to rock! Vintage Van Halen celebrates forty awesome riffs shred by Edward Van Halen. Built using the Sega Genesis Development Kit, Vintage Van Halen is available for free download from itch.io.

Let's check it out!

Note: Vintage Van Halen development based on SGDK Programming Setup + SGDK Programming Sample. Download source code here.


Inspiration
Eddie Van Halen is regarded as one of the greatest guitarists of all time. His innovations revolutionized guitar playing and influenced generations of guitarists. Eddie is responsible for some of the most memorable riffs in rock history and his band "Van Halen" continues to remain as one of the world's top selling artists of all time.

Instructions
Simple: move the joystick Up and Down to select a multi-choice answer: 1, 2, 3, 4. Press button A to select an answer or progress forward through any prompts. Note: Press button B to always go back. Joystick Left and Right are not used at all. Finally, Press button C during the game play to replay any riff at any time!

Tools
Here are a list of Tools, Frameworks, Utilities and Emulators that were used in development of this project:
 Programming  SGDK
 Compiler  gcc 4.9.3
 IDE  Visual Studio 2015
 Languages  C / 68000
 Graphics  Image Resizer / BMP converter
 Music  Audacity / YouTube
 Emulators  Emulicious / Gens KMod

ROM Hacking
You can hack this ROM! Download + dump VintageVanHalen into Hex Editor, e.g. HxD, and modify bytes:
 ADDRESS  VARIABLE  DESCRIPTION
 0x004F  DelaySpeed  Used to speed through any game delay.
 0x0050  Invincible  Non-zero value always enables cheating.
 0x0051  RiffSelect  Set the value to 2,3,4 index otherwise 1.
 0x0052  DiffSelect  Set value to 1=Easy otherwise 2=Hard.

hack_manager.c
#ifndef __HACK_MANAGER_H__
#define __HACK_MANAGER_H__

#define PEEK(addr)       (*(unsigned char *)(addr))
#define POKE(addr, data) (*(unsigned char *)(addr) = (data))

#define HACKER_START  0x004F
void engine_hack_manager_load()
{
  struct_hack_object *ho = &global_hack_object;
  ho->hack_delayspeed = PEEK( HACKER_START - 2 );        // 0x01DE Used to speed through any game delay.
  ho->hack_invincible = PEEK( HACKER_START - 1 );        // 0x01DF Non-zero value enables always cheats.
  ho->hack_riffselect = PEEK( HACKER_START + 1 );        // 0x01E0 Set value to 2,3,4 index otherwise 1.
  ho->hack_diffselect = PEEK( HACKER_START + 2 );        // 0x01E1 Set value to 1=Easy otherwise 2=Hard.
}
#endif//__HACK_MANAGER_H__

Cheats
Hack the ROM [above] to show the answers for every quiz during entire game session or alternatively press button C five times on Title screen when prompted to "Press Start" to show the answers to the current quiz!

Also, on Title screen press + hold joystick down while holding button B. This will show all the game statistics persisted across all game sessions. Finally, on Splash screen press and hold button B to reset all game stats.

storage_manager.c
#ifndef _STORAGE_MANAGER_H_
#define _STORAGE_MANAGER_H_

void engine_storage_manager_code()
{
  sRamOffSet = 0x0000;
  signed char byte;

  SYS_disableInts();
  SRAM_enable();

  byte = SRAM_readByte( sRamOffSet++ );        // Read.
  SRAM_writeByte( sRamOffSet++, byte );        // Write.

  SRAM_disable();
  SYS_enableInts();
}
#endif//_STORAGE_MANAGER_H_

Credits
Extra special thanks goes to @MegadriveDev for the SGDK. Plus StevePro Studios would like to give thanks: @bigevilboss, @matteusbeus, @MoonWatcherMD, @ohsat_games, @SpritesMind for SGDK support online!



Summary
Vintage Van Halen is the first 16-bit project ever built by StevePro Studios for the Sega MegaDrive / Genesis. Fortunately, like Sega Master System, the MegaDrive community provides fantastic online help and support.

After years of developing for Sega Master System, it was seamless to apply many of the programming skills acquired from 8-bit development to 16-bit thus the project was completed in a very short time. Awesome J