HUC - huc_misc.asm file check

[dshadoff]

I would assume that farmemget function was left out of the documentation because explaining to the layman how it works might not be very easy. cd_fade was also left out of the documentation, and the only reason I can assume for that omission is the possibility that whoever wrote the documentation might not have understood the details of its parameter.

farmemget was added by David Michel, I think - as a proof-of-concept.  If I recall correctly, there were plans to expand and improve it, but they never happened.  The documentation was waiting for the upgraded version.

The graphics statements I was referring to above, were the very earliest versions of functions, implemented before we standardized a few things.  When we re-worked the overall basis of the compiler, they had become problematic but had been replaced by a whole new set of graphics functions.  They were only left in to allow people to port from 'old' to 'new', and that was why those function were never documented - because they weren't intended for use.

The CD_FADE and so on, were functions which exist in the CDROM card; I implemented all of those in a frenzy over about a week, using as much information as I had at my disposal - which was, at the time, the JApanese Develo Assembler book, which I could only understand about 30-50%.  The documentation in this case, was absent partly because the original documents weren't understood, and partly because documentation was taking a lot more time than actually programming it.

In those days, maybe 5 people were actually using HuC, so the cost/benefit of documentation just wasn't there.  You could easily say that the system was targetted at an audience of people who could already program, but had no experience in Assembler.  Most of the documentation is actually embedded in the comments of the assembler source code "include" files, as a sort of training manual for assembler.

[Arkhan]

In those days, maybe 5 people were actually using HuC, so the cost/benefit of documentation just wasn't there.  You could easily say that the system was targetted at an audience of people who could already program, but had no experience in Assembler.  Most of the documentation is actually embedded in the comments of the assembler source code "include" files, as a sort of training manual for assembler.

...this is precisely why more people didn't join the PCE programming club, and why we still have a piddly amount of people actively doing anything.   The documentation is a bit out of line with what you find on just about any other platform people get into as a hobby.  It's not a very accessible system for newcomers or people who are trying to learn this stuff in the first place. 

I even remember spotting a comment in one of the documents that basically said "I am lazy and don't feel like doing this."

Proper documentation is how you get more people to show up to the party.   The cost/benefit only gets better when you actually do it so that more people are encouraged to get involved.



we managed to make the PSG library and MML setup work using a katakana chart, research into how other platforms (MSX) do it, a few weeks of screwing around, and a lot of caffeine.    I wrote a giant manual and provided examples.   As a result, people use it.    A few of them aren't even programmers.  They're just musicians.



If you build it, they will come.

[nodtveidt]

Arkhan, you hit the nail on the head so hard that it went through the damn board.

One of the biggest detriments when I was first getting started was the lack of proper documentation. I had to largely rely on my own experience with C and a huge amount of trial and error. That's why I had started hucdoc some time later, then contributed to archaicpixels, and then finally started obeybrew.com. Since starting obeybrew.com, several new people have gotten into coding, just as Squirrel got several new people into doing music on the PCE. Squirrel's main strength isn't only its power in and of itself, it's also the extensive documentation. That makes it truly useful. If HuC itself had Squirrel's level of documentation, we'd have a lot more development teams in the scene. That's one of my goals with obeybrew.com.

[Arkhan]

The goal with the PC Engine should have been to make it as accessible as something like the MSX or the C64.   There is no shortage of detailed documentation for either of those computers. 

That's part of why they both have new stuff coming out all the damn time, lol

[dshadoff]

In those days, maybe 5 people were actually using HuC, so the cost/benefit of documentation just wasn't there.  You could easily say that the system was targetted at an audience of people who could already program, but had no experience in Assembler.  Most of the documentation is actually embedded in the comments of the assembler source code "include" files, as a sort of training manual for assembler.

...this is precisely why more people didn't join the PCE programming club, and why we still have a piddly amount of people actively doing anything.   The documentation is a bit out of line with what you find on just about any other platform people get into as a hobby.  It's not a very accessible system for newcomers or people who are trying to learn this stuff in the first place.  

I even remember spotting a comment in one of the documents that basically said "I am lazy and don't feel like doing this."

Proper documentation is how you get more people to show up to the party.   The cost/benefit only gets better when you actually do it so that more people are encouraged to get involved.

So fix it for crying out loud.  You have the power !

The tone of your post comes off sounding like blame for a failed product from a manufacturer who is profiting significantly from it; I can assure you that nothing could be farther from the truth.  We just wanted to make games.  I personally invested many hundreds of hours into HuC, and it is the best that it could be with the people who were contributing.

So let's change the dialogue a little.

Now that new people have come along and want some better documentation, do what we all did back then (but sadly don't have time for anymore) - write it.  Share it with others.  Pay it forward.  That's how HuC came to be born.  We all struggled with the machine, with the lack of English information, and we all wanted to make games.  We're all the same.

Nobody has a secret cache of information which is guarded from outsiders.  Nobody is withholding anything.  Nobody had a development team or a budget or an unlimited amount of time to create broad vistas of information.  This was never a product, only a hobby.  All the information that exists is either in the source code of the compiler, or demonstrated with the many code examples on zeograd.com .

I'm sorry that it hasn't (yet) turned out to be all things to all people, but on the other hand I'm pleasantly surprised that it has survived this long.  I'm very happy to see people (like The Old Rover) contributing to debugging and writing documentation.  I just don't know where some of the expectations come from.

[nodtveidt]

Dave, basically what Arkhan is saying is that the reality of the situation is the inverse of what was assumed. Those who worked on the system assumed that since no one was really using it, it didn't need extensive documentation; the reality of it is that if it had extensive documentation, more people would use it. obeybrew.com provided evidence of this quite handily. If the documentation had been better back then, there would likely be more teams making games nowadays. That's his point, and it's a very true point. That's not to say that Arkhan is dissing you, because he isn't. It sounds like you are taking what he said a little too personally; don't. He's not attacking you or anyone else who worked on it, he's just making note of the well-established principle that the more documented a system is, the more users it will attract.

[Bonknuts]

I really don't think that's the problem. Well, that might be an issue for some coders that really just want a quick setup to put something out there, but there are other coding scenes for consoles where they were in the same boat and they over came such issues without relying on just a hand full of people. I think the biggest problem with attracting people to code for the TG16/PCE, is the popularity of the system itself. Hell, the SMS probably has a bigger fan base than the PCE. But either way, a console coder is a different type of breed IMO, and will find away around whatever limitations the tools present (including writing all new tools/assemblers). The NES is prime example of this. There are quite a few assemblers for it, and many people have written their own sound engines (and format) from scratch.

 I can see the point being made, but it doesn't account for ~all~ the lack of interest in developing for the PCE/TG16. I would guess not even a fourth of the reasons.

 That said, if HuC is crap - why isn't something new written already? It's been what, 10 years or more since the peek of HuC interest? Being part of the solution and all that sort of nonsense?

 Anyway, my point is that if people really wanted to code for the PCE - then they'd find a way. They'd improve HuC or write something new, or whatever. It's just the simple fact that the PCE just isn't that popular for the console coding scene, outside a very few small dedicated coders. I didn't want to believe this at first, but being part of other console dev scenes (and trying to get coders to try out the PCE system) - it's become very apparent to me.

[dshadoff]

Dave, basically what Arkhan is saying is that the reality of the situation is the inverse of what was assumed. Those who worked on the system assumed that since no one was really using it, it didn't need extensive documentation; the reality of it is that if it had extensive documentation, more people would use it.

I appreciate what you're trying to say, but the truth is that nobody was making assumptions about what needed to be done; there simply weren't any people available to work on the compiler, let alone to use it.  The documentation wasn't glossed over as an unnecessary extravagance, it was the number two priority after getting the compiler operational (without which, the compiler documentation would be extraneous).  As you can see, the number one priority of getting the compiler operational had barely enough resources to squeak by, and there were no resources left over for documentation.

It sounds like you are taking what he said a little too personally; don't. He's not attacking you or anyone else who worked on it, he's just making note of the well-established principle that the more documented a system is, the more users it will attract.

Perhaps I am taking it a bit too personally... but I've received pretty similar and consistent comments for the past 10 years (across a variety of individuals):
- vague dissatisfaction that it doesn't do 'X' (some technically complex operation),
- performance is less than 'Y' (some modern piece of personal electronics),
- documentation is not up to professional standards
...and comments like these are easy to accept if they are phrased in a direct and unemotional tone, because there are logical reasons for things to be that way.

But what seems to irk me is the boldfaced expectation that this should not be the case, even on a one-man, spare-time hobby project, and the apparent shock when suggested that their participation would benefit the product, and help give everybody a more pleasant experience.

Sadly, I can't recall a time when there was a compliment or expression of gratitude for the work invested in HuC.  Maybe I received one, but if I did, I can't remember it anymore.

Basically, I think Bonknuts has it completely right - it's not popular because the system itself is not popular.
It's not easy to program for, because the documentation itself is scarce, because it was all discovered and published by a very small group of very dedicated people.
The tools are crude because they were written by the same small group of people.
The documentation is lacking because... wait for it.... same small group of people.

And when I say small, I mean small.  There's maybe 4 or 5 people in the past 20 years who have created 90% of all the (apparently inadequate) technical resources for the system.

And this is why I applaud anyone who contributes to the ecosystem.

[nodtveidt]

Sadly, I can't recall a time when there was a compliment or expression of gratitude for the work invested in HuC.  Maybe I received one, but if I did, I can't remember it anymore.

You got one from me about 8 or 9 years ago when we were chatting on IRC and discussing possibly writing new sound routines. I remember it clearly, because this was also around the time that Bt told me I'd be crazy to try writing an RPG (and then I went out and did it anyway to be defiant).

[Arkhan]

So fix it for crying out loud.  You have the power !

We all have already, in various forms.  This includes Squirrel, a few open sourced games on Aetherbyte.com, help with code that will ultimately make it into ObeyBrew.com or something (some of which helps get around HuC's quirks), and some other stuff that will eventually get sorted out and probably handed out to people.   

The tone of your post comes off sounding like blame for a failed product from a manufacturer who is profiting significantly from it; I can assure you that nothing could be farther from the truth.  We just wanted to make games.  I personally invested many hundreds of hours into HuC, and it is the best that it could be with the people who were contributing.

No, I'm just saying, you can't really accurately weigh in on cost/benefit for something that was never actually done.   It's a catch-22 of sorts.

Now that new people have come along and want some better documentation, do what we all did back then (but sadly don't have time for anymore) - write it.  Share it with others.  Pay it forward.  That's how HuC came to be born.  We all struggled with the machine, with the lack of English information, and we all wanted to make games.  We're all the same.

Agreed.  This is still being done.  That wasn't really ever up for debate.  The problem is finding people who want to wade through everything and sort it out.  You can barely find those people on the supposedly more popular systems like NES and C64. 

Believe me, I sat with a chart trying to figure out what words like "PAAKAASHON" meant (percussion).   It was a pain in the ass.  I had to bother some friends who were a bit more clued in about kanji to sort that out too for things like waveform.

I was mostly just commenting on the whole "cost/benefit" thing.  I'm the type of person where if ONE person benefits from a document I wrote, it was worth writing.  1:1 ratio, and all.    It only gets better from there.

If something was a pain in the ass for me to get going, I'd like to make sure I leave it in a state that is less of a pain in the ass for future readers.   Leaving comments throughout a bunch of assembler/source is still a pain in the ass.  It's just a different one.

That's all.

Nobody has a secret cache of information which is guarded from outsiders.  Nobody is withholding anything.  Nobody had a development team or a budget or an unlimited amount of time to create broad vistas of information.

I never said there was a secret cache of information.    I think we all wish there was some secret book-o-stuff.  That would rule.
 

I appreciate what you're trying to say, but the truth is that nobody was making assumptions about what needed to be done; there simply weren't any people available to work on the compiler, let alone to use it.  The documentation wasn't glossed over as an unnecessary extravagance, it was the number two priority after getting the compiler operational (without which, the compiler documentation would be extraneous).  As you can see, the number one priority of getting the compiler operational had barely enough resources to squeak by, and there were no resources left over for documentation.

Eh, it's been awhile, dude.  I think one of you could have organized something by now, seeing as you guys would be the best source for a documentation since you actually worked on it and were all there for the earliest stuff.   It mostly sounds like you guys are still going with that cost/benefit stance, and as a result, have not bothered.

It's similar to that time I mentioned a few of HuC's quirks to you and you said it wasn't worth fixing because of the cost/benefit. 

It's fine if you guys don't want to write documents anymore.  Just don't get worked up about it when people comment on the lack of them.

Sadly, I can't recall a time when there was a compliment or expression of gratitude for the work invested in HuC.  Maybe I received one, but if I did, I can't remember it anymore.

We all know this is mostly a thankless hobby.  You can assume that people using it and sticking with it to complete projects is thanks enough.  Just like how we assume people are saying thanks when they actually buy these games we slap together, and continue to pay attention to what we're doing.

FWIW, I am fairly certain we have thanks in our code in comments in a few places where people were expected to have read them. 

It's also in the credits for our games, thanking all of our forefathers, essentially.   Not by name, but by group.

Basically, I think Bonknuts has it completely right - it's not popular because the system itself is not popular.

Eh, I disagree.  At this point, every old system is popular.   It's not like the SMS is the most popular thing ever, and that thing's a bigger pain in the dick to program than the PCE will ever be.   

I've watched a handful of people come and go, trying to get involved with PCE development.  The lack of resources / documentation has scared them all off.  Hence, ObeyBrew and Squirrel.   

I've also watched people come to other scenes like the MSX scene, completely new to programming in general...

The documentation has allowed them to pick up assembler/the hardware easily enough to get games up and running in a matter of months.

And this is why I applaud anyone who contributes to the ecosystem.

It sort of sounds like you only applaud certain people, because you take things too personally.

[dshadoff]

The tone of your post comes off sounding like blame for a failed product from a manufacturer who is profiting significantly from it; I can assure you that nothing could be farther from the truth.  We just wanted to make games.  I personally invested many hundreds of hours into HuC, and it is the best that it could be with the people who were contributing.

No, I'm just saying, you can't really accurately weigh in on cost/benefit for something that was never actually done.   It's a catch-22 of sorts.

You've misunderstood and mis-characterized here.

What we can agree on, is that the documentation wasn't as plentiful as either of us would have liked.  But the cost/benefit analysis was not a choice between whether to do documentation or do nothing; it was always a question of whether to add a desperately-needed feature (ie. access beyond a single bank, boot from CDROM, access to CDROM-card functions, and at the end, an attempt at an MML player), fix bugs, or add documentation for what already existed (HuCard, single-bank "Hello World").

To say that the documentation was "something that was never done" is disingenuous.  There have always been documents, code examples, freely available source code, and significant comments inside all of the code.  There has never been enough information to spoon-feed newbies, but somebody with the will to learn has always had footholds to learn from.

Eh, it's been awhile, dude.  I think one of you could have organized something by now, seeing as you guys would be the best source for a documentation since you actually worked on it and were all there for the earliest stuff.   It mostly sounds like you guys are still going with that cost/benefit stance, and as a result, have not bothered.

It's similar to that time I mentioned a few of HuC's quirks to you and you said it wasn't worth fixing because of the cost/benefit. 

It's fine if you guys don't want to write documents anymore.  Just don't get worked up about it when people comment on the lack of them.

You're right.... what was I thinking ?
I should have spent the past ten years of my life in service to this compiler for your benefit.

By the way, who is "you guys" ?
It sounds like you assume there were more people involved with it over a longer period, with more hours available to dedicate to it.

David Michel spent a few weeks in early 2001 (maybe it was more, as this was a secret project at first) putting together the original version of the compiler, based on a freeware version he found for the 6502.  He released it for others to contribute to and play with.  It was built on top of MagicKit, which had been written by him a few years earlier but wasn't heavily used.  He put some cool optimizations into HuC, did a bunch of profiling, and worked on the innards of the compiler, but it was still pretty close to assembler at that point.

Zeograd spent a few weeks adding some macros and some functions to it to see whether a simple program could be written easily with it, and created the code repository (HuC Creations).  He also did a bunch of testing and debugging, and stayed around helping to manage releases and host the sourcebase.

I tinkered with it with them for the first little bit as a minor player (maybe a couple of months), then they got busy and slowed down.

It was at that point that I worked earnestly on writing library functions and the code optimization because I was between contracts (and decided to take a break for a while), and I was intent on seeing whether it was possible to have CDROM-based games written by hobbyists like myself (that CDROM bootstrap was the biggest investment of time of any piece of the compiler).  This went on for several months until it was time to go find a job again, and then there was no more time for me either.  A lot was accomplished; a lot was not accomplished either.  For example, I never really got anywhere on my own goals of writing a game.

That's where our story ends, and other peoples' story begins (roughly end of 2001).
...And I was the guy who thought HuC would probably be a waste of time when I first heard about it, and was reluctant to spend time on it.


In any case, my reaction would be completely different if your comments were of the form:

"The documentation isn't good enough, I'm going to write something"

rather than

"The documentation isn't good enough, you guys should have written more".


Taking a problem and projecting it onto somebody else doesn't help in solving the problem.

[Arkhan]

There has never been enough information to spoon-feed newbies, but somebody with the will to learn has always had footholds to learn from.

That's the one thing that was never done. Everything PCE related is a bit spread out across a bunch of places and not always all-there in the first place.

and "significant comments inside all of the code" isn't always true, anyway.   

Anyway, it's in the process of being done, now with ObeyBrew.com (Who do you think coined the term Obeybrew, anyway?  I'm glad it stuck.). 

It'll likely eventually turn into a one-stop shop for people to get information without having to go through the tedium of digging for things that they may not even find.

You're right.... what was I thinking ?
I should have spent the past ten years of my life in service to this compiler for your benefit.

Little melodramatic there, eh?   I think you're really over-playing how much work would have really gone into organizing a few documents...

By the way, who is "you guys" ?
It sounds like you assume there were more people involved with it over a longer period, with more hours available to dedicate to it.

You guys, meaning the entire bunch of you on TGHack (You, Zeograd, David Michel, that Jens guy that everyone says not to talk about, .. ), PCE Dev people...it took more than just the use of HuC to make these games, you know.   There was a lot of digging around involved.

That's where our story ends, and other peoples' story begins (roughly end of 2001).
...And I was the guy who thought HuC would probably be a waste of time when I first heard about it, and was reluctant to spend time on it.

well, you were wrong about HuC being a waste of time.   So, you could also be wrong about how writing more elaborate docs would have been a waste of time...

"The documentation isn't good enough, you guys should have written more".
Taking a problem and projecting it onto somebody else doesn't help in solving the problem.

Well, you guys who worked on it sort of have that responsibility, given that it's your guys' project...

At least, that is MY stance on that.   If I make something, it's my job to produce as obnoxious a document as possible to help people use it...

It sucks though that HuC has not had any real updates since I've come around.  This includes that supposed MOD player that was coming "in a few weeks" almost right when I started getting interested.

I guess the bright side to that never actually happening is that Squirrel showed up, and it's better suited for use in games than a MOD player, anyway, due to sound effects.


Also, it's never too late for you to complete your goals of writing games for the PCE... go go go.

[TheOldMan]

There has never been enough information to spoon-feed newbies, but somebody with the will to learn has always had footholds to learn from.

Understood. Documentation is not meant to teach someone with no knowledge of programming how to program. However, when some one who knows what they are doing gives up using the tools because they can't figure out basic things like sprites and backgrounds from the documentation, we all lose.

See here for responses to many of your arguements.
http://stevelosh.com/blog/2013/09/teach-dont-tell/

And remember, documentation is not something done -after- everything is done. It is something that should be done while things are being built, to explain why they are the way they are, and how to use them.

[Before you say "then fix it", we are trying. But like you, we have real lives. Unlike you, we have to go back and figure out the whats and whys of the functions before we can explain it to others.]

[nodtveidt]

Understood. Documentation is not meant to teach someone with no knowledge of programming how to program. However, when some one who knows what they are doing gives up using the tools because they can't figure out basic things like sprites and backgrounds from the documentation, we all lose.

This is exactly why I set out to write better docs. Very few people have my level of dedication to this craft... that's not bragging, it's just reality. I fumbled through the documentation, I tried in vain to comprehend the source, I spent countless hours performing trial-and-error tests on code I didn't completely understand (and that's with prior knowledge of the 6502, I should add), and finally, eventually, I had enough collective knowledge to put out a single game. The learning curve alone was about three years to gain enough knowledge of the system to write that RPG, and even nowadays, I can and AM doing a better job. How many people have the fortitude to hang on for that long? That's what I wanted to avoid for other hopefuls. I love this system and I want to see more people taking advantage of HuC and PCEAS, as they are both very good. All y'all who worked on them did a bang-up job, but we can't call it quits just there. The greatest system in the world is of no use if no one knows how to use it. My Crash Course In HuC series is designed to be an ongoing example of how to use HuC to program a complete game, and although I haven't been able to update it in some time now, it's gotten positive reactions so far. Things like that are how you build a successful system. The tools are only half the battle... gotta know how to use them too.

[Bonknuts]

I'm pretty sure it wasn't originally meant to be anything other than a novelty type thing (from what I've been told). I think, while additions were made for it (the lib grew, CD support, syscard lib extensions, etc) - it was never intended to be taken seriously. Not that it can't be (Ark, Rover, and others have proved what they can do with it), just that it wasn't meant to be. So, I don't think ~any~ responsibility falls on any of the original crew or contributors. If you wanted to do something serious, you used Assembly. And you wrote your own lib. Not really any different than any other platforms (homebrew consoles) for this era.



 On a side note, HuC has quite a bit more in the limitation department than just library documentation or library itself and such. No matter what you do, it will never match using straight assembly. It's more than just speed too; it's flexibility (in which speed optimizations can directly derive from). I've messed around a lot with HuC and wrote a lot of new library code for it (some public, some not). One issue always came up; balancing speed with flexibility. Not that this can't happen with writing library support for assemblers (and it does. But it's not that big of a problem because the library language and environment is the same as the source code being written), but it's much more of an issue with HuC (because of this processor arch). The library in HuC is all assembly. If you know enough of how the underlying hardware works *and* how to effectively write good/fast assembly code, to actually write new/faster/better code for it - then you know enough to use an assembler straight out. So it begs the question, why then even bother with HuC if you can handle assembly just fine? There really isn't a good answer to that. The only thing I can think of (and of the responses that I've seen or have been given), is that they aren't comfortable enough with assembler. Don't get me wrong, tinkering around with HuC was/is fun. But for anything serious (more than a year for development); that time would be better spent put into actually getting comfortable with doing a pure assembly project. It kind of reminds me of the coders that were BASIC interpreter loyalists. The ones that held on and refused to move onto something more adequate/beneficial/suited. Instead, patching lots of assembly into the code to make up for the all the sort comings. The whole HuC thing kinda fits in that category. The Genesis/Megadrive scene has this problem (quite a few people started out with the BASIC interpreter for the Genesis and have problems moving out of their comfort zone, onto C or assembly - but yet want all the benefits of C and assembly and such). Just my two cents; I'm sure many will disagree.



 Anyway, I don't think documentation is the problem/reason why the console doesn't have more devs for it. There's plenty of documentation for it. Sure, it might not all be in one place - but it's out there. Actually, not really much different than SMS, NES, SNES, or the Genesis scene. People that know how to code for these type of old consoles, WILL find that documentation. They'll figure it out. I did. I was able to find lots of info back in 2006. On the other hand, if you're a noob - documentation is probably the least of your problems; you already have a steep learning curve. I personally think the PCE has a pretty clean design. It's straight forward, much like the Genesis. The NES and SNES are convoluted and complex. The SMS less so, but still more complex than the PCE (because of the stricter limitations of the previous gen hardware).