I would like to cordially demand an update, even if it's something that I can't comprehend. Also, as I review & attempt to expand upon what little I learned about programming in college, I would like to cordially demand that you include more comments.

No

Fair enough.

Now that I finally have time to sit in front of my computer:


For #1, I'll just quote the jkhub forum about this, since I can't really word it better:



For #2, I'll say this:

In terms of documentation, Gorc can benefit most from (in order): more test coverage, a developers guide, and an architectural overview. Comments are not on that list.

Most of Gorc's components are self-explanatory even if how they fit together isn't. It should be obvious from names and test cases what things like cog::ir::code_printer and cog::stages::generate_code::lval_expression_visitor and event_bus and math::quaternion do even though those units are almost completely uncommented (and these are some of the most obscure ones!). The janky tight confusing algorithmic stuff is well-commented already and that's the absolute limit of how and where comments may occasionally be useful.

So, no. There will be no more comments. If you have general questions about what some code does I am happy to answer those questions pending a serious documentation effort.

I just wanted to say that, especially as a 'hobby project' as you called it, it's nice to see a developer prioritize testing in importance. It's disappointing when that's not prioritized in actual 'professional' projects.

Gorc's line coverage is 56% for non-gameplay code. That is honestly not good. Testing has always been a priority, but I didn't start measuring test coverage until about a year ago.

I don't have anything set up for sharing these results to other developers, but here's what the project looks like right now in terms of testing.

Project Coverage summary

[TABLE="class: pane, width: 1503"]
[TR]
[TH]Name[/TH]
[TH="class: center, align: center"]Packages[/TH]
[TH="class: center, align: center"]Files[/TH]
[TH="class: center, align: center"]Classes[/TH]
[TH="class: center, align: center"]Lines[/TH]
[TH="class: center, align: center"]Conditionals[/TH]
[/TR]
[TR]
[TD]Cobertura Coverage Report[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]89%[/TD]
[TD][CENTER]32/36[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]74%[/TD]
[TD][CENTER]264/355[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]74%[/TD]
[TD][CENTER]264/355[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]56%[/TD]
[TD][CENTER]4714/8418[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]14%[/TD]
[TD][CENTER]4780/33347[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[/TABLE]
Coverage Breakdown by Package

[TABLE="class: pane sortable, width: 1503"]
[TR]
[TH]Name[/TH]
[TH="class: center, align: center"]Files[/TH]
[TH="class: center, align: center"]Classes[/TH]
[TH="class: center, align: center"]Lines[/TH]
[TH="class: center, align: center"]Conditionals[/TH]
[/TR]
[TR]
[TD]src.base[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]2/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]2/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]12%[/TD]
[TD][CENTER]2/17[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]23%[/TD]
[TD][CENTER]3/13[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.content[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]5/10[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]5/10[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]9%[/TD]
[TD][CENTER]5/57[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]5%[/TD]
[TD][CENTER]10/186[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.content.assets[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]71%[/TD]
[TD][CENTER]5/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]71%[/TD]
[TD][CENTER]5/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]7%[/TD]
[TD][CENTER]5/71[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]14%[/TD]
[TD][CENTER]10/72[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.content.loaders[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]3/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]3/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]9%[/TD]
[TD][CENTER]6/67[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]12%[/TD]
[TD][CENTER]19/163[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.diagnostics[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]93%[/TD]
[TD][CENTER]13/14[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]93%[/TD]
[TD][CENTER]13/14[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]42%[/TD]
[TD][CENTER]114/271[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]17%[/TD]
[TD][CENTER]70/423[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.events[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]40%[/TD]
[TD][CENTER]2/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]40%[/TD]
[TD][CENTER]2/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]36%[/TD]
[TD][CENTER]4/11[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]2/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.graphics[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]71%[/TD]
[TD][CENTER]5/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]71%[/TD]
[TD][CENTER]5/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]2%[/TD]
[TD][CENTER]5/220[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]3%[/TD]
[TD][CENTER]10/398[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.gui[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]67%[/TD]
[TD][CENTER]2/3[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]67%[/TD]
[TD][CENTER]2/3[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]1%[/TD]
[TD][CENTER]2/162[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]1%[/TD]
[TD][CENTER]4/362[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.gui.layout[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/3[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD="class: center, align: center"]N/A[/TD]
[/TR]
[TR]
[TD]src.base.gui.widgets[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]19/38[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]19/38[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]3%[/TD]
[TD][CENTER]19/585[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]5%[/TD]
[TD][CENTER]38/823[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.input[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]20%[/TD]
[TD][CENTER]1/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]20%[/TD]
[TD][CENTER]1/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]1%[/TD]
[TD][CENTER]1/68[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]4%[/TD]
[TD][CENTER]2/56[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.io[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]24/24[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]24/24[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]99%[/TD]
[TD][CENTER]559/562[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]56%[/TD]
[TD][CENTER]492/885[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.math[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]67%[/TD]
[TD][CENTER]4/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]67%[/TD]
[TD][CENTER]4/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]60%[/TD]
[TD][CENTER]184/309[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]31%[/TD]
[TD][CENTER]139/450[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.place[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/2[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.text[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]88%[/TD]
[TD][CENTER]7/8[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]88%[/TD]
[TD][CENTER]7/8[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]78%[/TD]
[TD][CENTER]213/273[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]41%[/TD]
[TD][CENTER]140/345[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.base.utility[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]91%[/TD]
[TD][CENTER]31/34[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]91%[/TD]
[TD][CENTER]31/34[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]94%[/TD]
[TD][CENTER]629/672[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]716/1440[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]99%[/TD]
[TD][CENTER]81/82[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]115/228[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.ast[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]4/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]4/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]97%[/TD]
[TD][CENTER]177/182[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]37%[/TD]
[TD][CENTER]187/512[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.grammar[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]66%[/TD]
[TD][CENTER]740/1119[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]52%[/TD]
[TD][CENTER]482/925[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.ir[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]83%[/TD]
[TD][CENTER]5/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]83%[/TD]
[TD][CENTER]5/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]135/268[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]38%[/TD]
[TD][CENTER]46/122[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.scripts[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]43%[/TD]
[TD][CENTER]3/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]43%[/TD]
[TD][CENTER]3/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]2%[/TD]
[TD][CENTER]3/165[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]2%[/TD]
[TD][CENTER]6/336[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.stages.1_generate_ast[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]1/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]1/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]4/4[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]4/8[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.stages.2_semantic_analysis[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]15/15[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]15/15[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]84%[/TD]
[TD][CENTER]400/478[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]46%[/TD]
[TD][CENTER]345/754[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.stages.3_constant_folding[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]5/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]5/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]205/205[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]55%[/TD]
[TD][CENTER]198/361[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.stages.4_generate_code[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]9/9[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]9/9[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]238/238[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]54%[/TD]
[TD][CENTER]163/301[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.symbols[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]5/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]5/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]79%[/TD]
[TD][CENTER]61/77[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]40%[/TD]
[TD][CENTER]45/112[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.verbs[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]7/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]7/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]74%[/TD]
[TD][CENTER]56/76[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]1%[/TD]
[TD][CENTER]174/17976[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.cog.vm[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]93%[/TD]
[TD][CENTER]13/14[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]93%[/TD]
[TD][CENTER]13/14[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]89%[/TD]
[TD][CENTER]357/401[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]51%[/TD]
[TD][CENTER]286/563[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.content.assets[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]44%[/TD]
[TD][CENTER]15/34[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]44%[/TD]
[TD][CENTER]15/34[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]26%[/TD]
[TD][CENTER]68/265[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]11%[/TD]
[TD][CENTER]101/912[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.content.loaders[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]12/24[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]50%[/TD]
[TD][CENTER]12/24[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]3%[/TD]
[TD][CENTER]34/1041[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]8%[/TD]
[TD][CENTER]233/2971[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.content.vfs[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]86%[/TD]
[TD][CENTER]6/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]86%[/TD]
[TD][CENTER]6/7[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]75%[/TD]
[TD][CENTER]88/117[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]40%[/TD]
[TD][CENTER]136/342[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.content.vfs.episode[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]80%[/TD]
[TD][CENTER]4/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]80%[/TD]
[TD][CENTER]4/5[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]86%[/TD]
[TD][CENTER]48/56[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]43%[/TD]
[TD][CENTER]57/132[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.content.vfs.gob[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]6/6[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]76%[/TD]
[TD][CENTER]50/66[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]48%[/TD]
[TD][CENTER]29/60[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.game.world.components[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD="class: center, align: center"]N/A[/TD]
[/TR]
[TR]
[TD]src.game.world.physics[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/1[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]0%[/TD]
[TD][CENTER]0/2[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[TR]
[TD]src.test.impl[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]19/19[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]19/19[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]100%[/TD]
[TD][CENTER]221/221[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[TD][TABLE="class: percentgraph"]
[TR]
[TD="class: data"]47%[/TD]
[TD][CENTER]518/1108[/CENTER]
[/TD]
[/TR]
[/TABLE]
[/TD]
[/TR]
[/TABLE]

Since this is all easily-tested utility code, the coverage should be around 100%, with conditionals around 50%.

Damn shame vb stripped the color of out the above chart.

Do you have any updated windows builds you could post?

What Linux distro are you developing on?

No updated windows builds right now. The only recent finished change was a contributed patch to enable the rest of the hud. Which would be good, but I'm in the middle of reworking some of the physics, and things aren't quite stable yet.

I develop on Ubuntu 14.04.

:saddowns:

I spent an entire long weekend trying to get a macosx build working. I couldn't. I don't understand macosx and frameworks and app bundles and ****. why cant it just be like linux, noesc

why



If an osx uses a framework how do I distribute it? sos are bad enough but at least you can LD_LIBRARY_PATH. I don't want to make an installer. Agh.

Suck it up, buttercup.

Just kidding. This thread just happened to catch my eye the other day. Absolutely phenomenal work, man, but, just out of curiosity, why? I mean I get that it is a hobby project but at this stage in the lifespan of JK, what's your motivation to keep working on Gorc? Is this a labor of love, so to speak? I am certainly not trying to dissuade you from continuing with your project. I find it remarkable to see you continuing to work on it.

Perhaps a better way to ask this is what enjoyment/benefit/experience are you getting out of this when the plain fact is that most likely only a tiny number of people will ever use Gorc?

The fun is in the work itself. He probably doesn't care if anyone actually uses it.

That's what I assume but I was just hoping he would elaborate.

There's another reason to complete gorc: to have an open source reverse-engineered rendition of the Sith Engine in which programmers could be able to create games in the style of Jedi Knight and Mysteries of the Sith without the restraints of the original games. The Sith Engine is one of my favorite classic engines, and I long to make games in an engine very much like it. The Sith Engine after all gave us JK, MotS, Shadows of the Empire, Indiana Jones and the Infernal Machine, and Grim Fandango, and yet the source code is not available. Why not have gorc? A small percentage of people may use it, but the same could be said for DarkXL.

What I hope is that when gorc is completed, editors might have more freedom to pull off more ambitious levels and mods which we have yearned for. I'll look forward to the day when gorc is finished, as well as looking forward to seeing what the editors of Massassi and JK Hub will do with it.

As mentioned in another thread, I've been working on an improved COG semantic analyzer for Gorc. This work may be useful for JK level designers, but was mainly intended as a debugging aide. Unfortunately there are a lot of careless mistakes in LEC's COGs, for example passing thing IDs to verbs expecting sector IDs, and I've discovered that it's very difficult to identify exactly what's going on.

The new analyzer tries to statically detect unsafe ID use, but it won't reject scripts that it can't statically prove are safe. Instead, Gorc now performs an added dynamic type check. So Gorc will let you assign a thing ID to an int symbol, and then use it as though it were a thing id. However, if you try to pass '50' to a verb expecting a thing ID, it won't work anymore.

For fun, I've attached an excerpt of the work-in-progress analyzer when run against all of JK's COG scripts. I've stripped out warnings for unsafe conversions from int to thing and a couple of other minor things, but the big, fun problems are all listed there. :mryuck:

Always glad to see some Gorc updates.

Amazing. I always knew that COGs were poorly written, but this is just incredible. Especially things like "label 'arrived' flows into label 'pulse'". How does that even work? Do you think that the LEC COG runtime has some kind of safety net for such mistakes, or were these scripts just usable enough to pass QA and be left alone forever? My hunch is that verb implementations were constantly tweaked in order to cover script writers' sloppiness, probably with many level-specific patches and hacks.

On a side note, fantastic work Jon, this project is a real joy to follow.

It's legal for message handlers to flow through, it's just unwise. There is a safety net for some mistakes but it is of the PHP sort, meaning JK prefers to handle all problems by behaving randomly until it crashes. JK does no meaningful semantic analysis of COG and does not report problems, so even if the level designers knew what they were doing, they were never given the tools to do it. It's honestly a miracle that the game is as stable as it is.

Here are some of the other interesting things I've found:


c3_fanspuzzle.cog calls SetColorMap with a sector ID and int 0. This seems to reset the sector colormap to the master colormap. This makes a certain amount of sense, since the master colormap is by definition the first colormap listed in the jkl, but I'm otherwise not thrilled about it.


Label fall-through that only a C greybeard could love. I don't want to do a full audit of this, but it's not a good sign. It's too easy to mess up. Most C static analyzers treat label fall-through as a defect today, for good reason.


A few cogs call 'SetTimer' with 4 arguments. The developer probably meant 'SetTimerEx'. e.g.: actor_fn.cog, actor_gd.cog.


Lots of assignments of the form 'dummy = foo()', even when the verb doesn't return a useful value.


Global symbols? 04_garage.cog and 08_slashgrate.cog assign (but do not read) undeclared symbols global4 and global1, respectively. I'm worried about the name choice. The strings 'global0' through 'global7' are specifically listed in JK.exe and probably do something special. Datamaster claims they're messages, but they don't seem to work. These variables could do something special that we don't fully understand.


04_garage.cog: the 'close doors' code is dead.


Early development cogs: during development the symbols section was changed significantly. I'm not sure if this syntax is still supported by JK, but I assume it isn't. Examples: slidetest.cog, gen_move.cog, door_switch.cog, togldoor.cog, redlight.cog, vectortest.cog, simple_door.cog, wallceltest.cog


A bunch of cogs put a mask extension on message symbols. Does this do anything? Considering how many there are, I'm sure there must be something here, but I don't think it's documented anywhere. e.g. 04_remotes2.cog, 06_generator.cog, class_roundturret.cog, 00_generator.cog, 04_remotes.cog, class_boxturret.cog, 08_irpuzzle.cog, class_boxturret4.cog, 04_remotes1.cog, 04_remotes3.cog


08_hiddenlight.cog redefines the startup message.


A bunch of cogs define pulse, but don't export it. That doesn't work, right? e.g. 12_thinglight.cog, 09_donefueling.cog, 03_thinglight.cog, 08_endlevel.cog


09_util_elev3.cog sets nolink on a sound. What? More examples: 09_drainpipes.cog.


09_util_elev3.cog tests undeclared symbol linkid. I assume the author's goal was to check the sender id. However, I can't tell at a glance what the activate handler is trying to do, so I'm not sure.


A bunch of messages that are exported, with no labels defined: 09_accessdoor.cog, 08_baydoors2.cog, 14_forcefield.cog, m10_lightningtrap.cog, 06_towerdoors.cog, 08_scelev.cog, 16a_timer.cog, 09_pipedoor_b.cog, weap_thermdet.cog


19_doortrigger.cog has a symbol named 'trigger' which it both gets and sets. This raises an interesting question about constants. Would it use the trigger symbol, would it use the constant message id for trigger, or is the correct definition chosen contextually? Same thing shows up other places: 06_max.cog


jkendlevel is often used with too few arguments. This probably works by accident. I believe the sentinel value at the bottom of the stack is -1, so jkendlevel() ~= jkendlevel(-1) which ends the level with success. Pretty annoying.


08_baydoors2.cog: has startup and loading handlers, but does not export them. Another: 06_atstelev.cog


00_ziplight.cog: uses verb 'getsector'. Does this verb exist? It's not listed in Datamaster. Maybe it's supposed to be getthingsector.


darkjedi_gorc.cog: calls stopkey with 2 arguments


darkjedi_maw.cog: also calls stopkey with 2 arguments


14_forcefield.cog: "StopSound(dummy1, 0,0)" because I am from Europe and my computer magically knows it.


09_hiddenlight2.cog: exports 'startup' twice


c3_randomwaterambient.cog: calls 'rand' with an argument. It's worth saying... these are by YB. Makes me think that JK's rand verb really does take an argument.


ctf_displayscore.cog puts nolink on an int.


20_bocsearch.cog: defines vector symbol currNode, then treats it like an int in the rest of the cog. This works fine, but it's a bit silly.


m4_reactorthrust.cog: interesting idea of how the desc extension is supposed to work. Runners up: 00_soundtrack.cog, 01_soundtrack.cog


00_aishootbarrel.cog: calls aisetlookpos with a thing instead of a vector. Other cogs make the same call with getthingpos, so this probably shouldn't work. Other examples: 11_endlevel.cog, 06_drama.cog


10_endlevel.cog: calls label 'close_doors', but it's not defined.


force_pull.cog: if(GetThingType(potential == 5))? Really?


19_counterweight.cog: GetSenderId(GetSenderRef()).


06_doorstrick.cog: SectorAdjoins(thingid, 0). Since a later line has SectorAdjoins(GetThingSector(thingid), 0), I'm guessing this is a mistake.


09_fueltanks.cog: Passes a surface ID as the thing to PlaySoundThing.


00_aisidekick.cog: AISetMoveThing(sidekick, GetThingPos(master)). Close but no cigar.


levelsong.cog: Calls playsong with 1 argument


16a_catwalk.cog: Uses extension 'nolink1' [sic]. Twice.


21_jerecai.cog: AISetMoveSpeed(1.5). Note that JK runs this anyway, even though it doesn't have enough arguments, back-filling with garbage. Dunno what thing gets a 1.5 move speed, but it's probably not Jerec.


06_thirddoor.cog doesn't end with 'end'. Others: 08_vents2a.cog


18_finalthrust1.cog: symbol 'litepower' is redefined; one is a float, the other is a local int.


09_chopgrate.cog: CaptureThing([template id]). Sure hope it wasn't important.


19_startup.cog: "WaitForStop;" Very confused, is this supposed to work? If so, how?


00_backpack.cog: Calls a verb 'addtint'. If this is a legal verb, it's not documented anywhere.

I love that list. I gotta wonder how many of those nastier errors were worked around by patching the cog parser instead of fixing the cogs.

Current work has been pushed into the 'next' branch. See: https://github.com/jdmclark/gorc/tree/next

I'm in California but my big machines aren't, so no builds. However, if you're willing to use Linux, it should be easy to build and test your scripts against it.

After building, run the following: ./pkg/bin/cogcheck --file <filename>

You can also use the --dump-ast option to, well, dump the ast.

I can't promise my understanding of COG is complete. I've certainly lost track of some details in the almost two years since I first wrote gorc's cog analyzer. So, if you encounter what you consider incorrect behavior, I hope you will file a github issue.

Oh, based on my recent work, I've found another new fun thing:



Snippet:



In order to understand exactly what this code does, it's important to note that JK does not implement assignment expressions correctly. For example, you would expect that this statement:



is equivalent to:



but it is, in fact, in COG, equivalent to:



So what did the developer intend to do? They most likely meant to compare bargh to 0, and run some code if they are equal.

What would you expect this code to do? Set bargh to 0, but never run the code.

What does it actually do? Sets bargh to 0. And then it always runs the code.

JK works by accident.

True words. I tried figuring out how to make allies attack enemy characters in JK, changing the AI alignment number didn't help so I dug up this tutorial from ages beyond and before trying it out, I read the last sentence on the page. Oy.

Yeah. I can't believe he had a netcom.com email account.