Release 1.2.6 not shown in the front page of https://github.com/sean-gugler/u4remasteredA2

wyatt-wong commented 2 years ago

I was just wondering, how come the release 1.2.6 was NOT shown in the front page of https://github.com/sean-gugler/u4remasteredA2 ?

The Release 1.2.6 can only be found in https://github.com/sean-gugler/u4remasteredA2/releases.

Furthermore, why the source codes are NOT shown in this GitHub page but only in the format of zip file ?

sean-gugler commented 2 years ago

Oh, I forgot to update the "main" branch when I released 1.2.6. Thank you for mentioning that! I have just pushed an update.

The source codes are not in the "main" branch. They are in two other branches, so you can choose which version of the source you want to see:

documented is for studying the retail edition with annotated, reconstructed source code.
fixed includes all the enhancements. This branch is used to build the zip files in the Releases section.

wyatt-wong commented 2 years ago

Oh, I forgot to update the "main" branch when I released 1.2.6. Thank you for mentioning that! I have just pushed an update.

The source codes are not in the "main" branch. They are in two other branches, so you can choose which version of the source you want to see:

documented is for studying the retail edition with annotated, reconstructed source code.

fixed includes all the enhancements. This branch is used to build the zip files in the Releases section.

Yes. I saw you mentioned the source code was not in the main branch from your README, but I would like to know why ?

And as you also mentioned the remastered require a total rebuild, so where did you obtain the source code of Ultima IV at the very beginning ?

sean-gugler commented 2 years ago

"Why not the main branch" you ask? Good question! I'm not sure I remember :-) Probably because at the time, I wasn't sure which purpose should be primary. I couldn't guess whether visitors would prefer the documented retail analysis or the enhanced fixes, so I let them choose.

As for the source code, I explain this in the README:

This source code has been reconstructed by disassembling and symbolicating the 1985 binary code released for Apple II series computers. It likely bears little resemblance to the original source, but it can be used by modern tools to build the same playable binaries.

...

MagerValp/u4remastered for Commodore 64 was the starting point for much of the symbolication and the project layout.

Additional work by Sean Gugler, including portions taken from his C64 fork of u4remastered

"Disassembling" means converting a binary stream of bytes into an assembly code text file. For example, A9 13 85 0E 20 C8 45 20 01 84 4C 75 63 becomes this:

$43BC: A9 13               LDA #$13
$43BE: 85 0E               STA $0E
$43C0: 20 C8 45            JSR $45C8
$43C3: 20 01 84            JSR $8401
$43C6: 4C 75 63            JMP $6375

"Symbolicating" means replacing numbers with symbols that make the code easier for a human to understand. The above disassembly turns into this:

tile_ship_south = $13
player_transport = $0E
...
@set_ship_facing:
    lda #tile_ship_south
    sta player_transport
    jsr print_turn
    jsr print_south
    jmp cmd_done

The symbol names were invented by MagerValp or me based on careful human analysis of what effect each part of code has upon the game.

This whole process is sometimes referred to as "reverse engineering".

wyatt-wong commented 2 years ago

"Why not the main branch" you ask? Good question! I'm not sure I remember :-) Probably because at the time, I wasn't sure which purpose should be primary. I couldn't guess whether visitors would prefer the documented retail analysis or the enhanced fixes, so I let them choose.

As for the source code, I explain this in the README:

This source code has been reconstructed by disassembling and symbolicating the 1985 binary code released for Apple II series computers. It likely bears little resemblance to the original source, but it can be used by modern tools to build the same playable binaries.

...

MagerValp/u4remastered for Commodore 64 was the starting point for much of the symbolication and the project layout.

Additional work by Sean Gugler, including portions taken from his C64 fork of u4remastered

"Disassembling" means converting a binary stream of bytes into an assembly code text file. For example, A9 13 85 0E 20 C8 45 20 01 84 4C 75 63 becomes this:
$43BC: A9 13               LDA #$13

$43BE: 85 0E               STA $0E

$43C0: 20 C8 45            JSR $45C8

$43C3: 20 01 84            JSR $8401

$43C6: 4C 75 63            JMP $6375
"Symbolicating" means replacing numbers with symbols that make the code easier for a human to understand. The above disassembly turns into this:
tile_ship_south = $13

player_transport = $0E

...

@set_ship_facing:

  lda #tile_ship_south

  sta player_transport

  jsr print_turn

  jsr print_south

  jmp cmd_done
The symbol names were invented by MagerValp or me based on careful human analysis of what effect each part of code has upon the game.

This whole process is sometimes referred to as "reverse engineering".

Well so now after releasing up to beach 1.2.6, the source code can be add to the main branch so all users of GitHub can read the source code from your page and fork it to make changes.

I knew what is reverse engineering and thanks for your detail explanation. I am a low-tech software developer in the past and am still working in the low-tech IT industry now, though I seldom develop software nowadays.

But what I actually meant is, is it really possible to disassemble the binaries back to source code and reconstructing the symbol names, jump references, identified the code block and data block (such as shape tables), adding comments back ? And part of the Ultima IV source code was in fact written in Applesoft BASIC and I don't think you can reconstruct it back into the BASIC form. The Disk Analyzer of Applesauce was able to view the disk files of the WOZ format of Ultima IV. I remembered I was able to view the Applesoft BASIC files in textual form as well if I was not mistaken.

I supposed the answer was a POSITIVELY YES (in certain extent) as you have already did it. But then posting the "source" in the main branch for online viewing would be more useful than requiring user to download the zip file and view the "source" offline. And I supposed this essentially defeat the purpose of using GitHub, by making it simply as a repository instead of online reviewing, editing as well as a software repository...

sean-gugler commented 2 years ago

You absolutely can view my source online and fork from it. I even provided links above; I'll repeat them here:

You can even select a branch directly from any GitHub project's main page:

github_branch_selection

You might find it helpful to read some tutorials about git branches and how GitHub lets you display and compare them. Cheers!

sean-gugler / u4remasteredA2

Release 1.2.6 not shown in the front page of https://github.com/sean-gugler/u4remasteredA2 #13