This automatically generates documentation from goal_src docstrings,
think doxygen/java-docs/rust docs/etc. It mostly supports everything
already, but here are the following things that aren't yet complete:
- file descriptions
- high-level documentation to go along with this (think pure markdown
docs describing overall systems that would be co-located in goal_src for
organizational purposes)
- enums
- states
- std-lib functions (all have empty strings right now for docs anyway)
The job of the new `gen-docs` function is solely to generate a bunch of
JSON data which should give you everything you need to generate some
decent documentation (outputting markdown/html/pdf/etc). It is not it's
responsibility to do that nice formatting -- this is by design to
intentionally delegate that responsibility elsewhere. Side-note, this is
about 12-15MB of minified json for jak 2 so far :)
In our normal "goal_src has changed" action -- we will generate this
data, and the website can download it -- use the information to generate
the documentation at build time -- and it will be included in the site.
Likewise, if we wanted to include docs along with releases for offline
viewing, we could do so in a similar fashion (just write a formatting
script to generate said documentation).
Lastly this work somewhat paves the way for doing more interesting
things in the LSP like:
- whats the docstring for this symbol?
- autocompleting function arguments
- type checking function arguments
- where is this symbol defined?
- etc
Fixes#2215
This PR adds a feature to merc2 to update vertices. This will be needed
to efficient do effects like blerc/ripple/texture scroll. It's enabled
for blerc in jak 1 and jak 2, but with a few disclaimers:
- currently we still use the mips2c blerc implementation, which is slow
and has some "jittering" because of integer precision. When porting to
PC, there was an additional synchronization problem because blerc
overwrites the merc data as its being read by the renderers. I _think_
this wasn't an issue on PS2 because the blerc dma is higher priority
than the VIF1 DMA, but I'm not certain. Either way, I had to add a mutex
for this on PC to avoid very slight flickering/gaps. This isn't ideal
for performance, but still beats generic by a significant amount in
every place I tested. If you see merc taking 2ms to draw, it is likely
because it is stuck waiting on blerc to finish. This will go away once
blerc itself is ported to C++.
- in jak 1, we end up using generic in some cases where we could use
merc. In particular maia in village3 hut. This will be fixed later once
we can use merc in more places. I don't want to mess with the
merc/generic selection logic when we're hopefully going to get rid of it
soon.
- There is no support for ripple or texture scroll. These use generic on
jak 1, and remain broken on jak 2.
- Like with `emerc`, jak 1 has a toggle to go back to the old behavior
`*blerc-hack*`.
- In most cases, toggling this causes no visual differences. One
exception is Gol's teeth. I believe this is caused by texture coordinate
rounding issues, where generic has an additional float -> int -> float
compared to PC merc. It is very hard to notice so I'm not going to worry
about it.
Adding support for better child-type method docstrings. This is a
problem unique to methods.
Usually, a child-type will have the same signature and a common name
will apply, but the implementation is different. This means, you
probably want a different docstring to describe what is happening.
Currently this is possible to do via `:replace`. The problem with
replace is two fold:
- a replaced method ends up in the generated `deftype`...because you
usually change the signature!
- we don't put docstrings in the `deftype` in normal GOAL, this is just
something we do for the `all-types` file (they go in the `defmethod`
instead)
- more importantly, this means anytime you now want to change the
parent's name/args/return type -- you have to apply that change
everywhere.
So this is a better design you can now just declare the method like so:
```clj
(:override-doc "my new docstring" <method_id>)
```
And internally a pseudo-replaced method will be added, but it will
inherit everything from the parent (except the docstring of course)
Unrelated - I also made all the keyword args for declaring methods not
depend on ordering
This also adds support for documenting virtual and non-virtual state
handlers. For example:
```clj
(:states
(part-tester-idle (:event "test") symbol))
```
or
```clj
(idle () _type_ :state (:event "test") 20)
```
I will probably add the ability to give some sort of over-view docstring
at a later date.
Co-authored-by: water <awaterford111445@gmail.com>
- started documenting the files I glossed over, some are totally done,
others are just partially done
- I changed the decompiler to automatically initialize the
art-group-info from the json file. This makes updating gsrc, even a
single file at a time, have consistent naming
- Though I disabled this functionality for jak 1, as I have no idea if
using the ntsc art groups will cause a regression for different versions
- fix indentation for docstrings -- it still doesn't look great, but
this is now a formatting concern, rather than the docstring having a
bunch of happen-stance leading whitespace.
Effects the following files:
- [x] vehicle-rider
- [x] vehicle-control
- [x] vehicle-effects
- [x] vehicle
~~- [ ] vehicle-util~~
- [x] vehicle-physics
- [x] vehicle-states
~~- [ ] vehicle-guard~~
~~- [ ] traffic-engine~~
~~- [ ] traffic-manager~~
With the exception of traffic-engine, most of these files are either
done or have 1-3 stubborn functions remaining. Draft while I try to
resolve as many as possible / cleanup names and such.
Co-authored-by: water <awaterford111445@gmail.com>
This solves two main problems:
- the looming threat of running out of memory since every thread would
consume duplicate (and probably not needed) resources
- though I will point out, jak 2's offline tests seem to hardly use any
memory even with 400+ files, duplicated across many threads. Where as
jak 1 does indeed use tons more memory. So I think there is something
going on besides just the source files
- condense the output so it's much easier to see what is happening / how
close the test is to completing.
- one annoying thing about the multiple thread change was errors were
typically buried far in the middle of the output, this fixes that
- refactors the offline test code in general to be a lot more modular
The pretty printing is not enabled by default, run with `-p` or
`--pretty-print` if you want to use it
https://user-images.githubusercontent.com/13153231/205513212-a65c20d4-ce36-44f6-826a-cd475505dbf9.mp4
Favors the `lg` namespace over `fmt` directly, as this will output the
logs to a file / has log levels.
I also made assertion errors go to a file, this unfortunately means
importing `lg` and hence `fmt` which was attempted to be avoided before.
But I'm not sure how else to do this aspect without re-inventing the
file logging.
We have a lot of commented out prints as well that we should probably
cleanup at some point / switch them to trace level and default to `info`
level.
I noticed the pattern of disabling debug logs behind some boolean,
something to consider cleaning up in the future -- if our logs were more
structured (knowing where they are coming from) then a lot this
boilerplate could be eliminated.
Closes#1358
* jak1: put common speedrunning code into it's own file
* jak1: enforce `60` fps while in speedrunning mode
* jak1: when speedrunning, display the version until you get the first powercell
* jak1: add an explicit option for skipping cutscenes
* jak1: extend `game-option` to allow any menu option to be disabled
* tests/jak1: allow whitelisting types to be redefined to satisfy typeconsistency checks
* jak1: add file headers
* jak1: cleanup bool checking
* test: delete the es substitle file
* test: add it back
* jak1: missed one cleanup spot related to bool comparisons
* decomp: add `docstring` support to relevant places in `all-types`
* decomp: output method docstring into the `defmethod` instead
* goalc: handle docstrings in `define[-extern]` (gracefully ignore for now)
* decomp: output docstrings for bitfield deftypes too
* goalc: fix `defenum` parsing when coming from the compiler (no symbol metadata to store to)
* lsp/tests: fix ups
* lint: formatting
* goalc: handle edge-case of defining a string constant
* cleanup leftovers, fix codacy issues, rename struct
* lsp: json-rpc example is working, a decent place to start...
* lsp: vendor library
* lsp: cleanup and time to get started
* lsp: commit what i got so far
* lsp: example `initialize` payload
* lsp: switch to `stdio`
* stash
* modularize the lsp implementation
* lsp: implement first actual LSP feature - function names in outline
* lsp: produce document diagnostics
* lsp: remove unused third-party lib
* lsp: support hovering MIPS instructions in IR files
* lsp: basic go-to all-types definition
* stash
* lsp: cleanup code, just need to add it to the release artifacts
* fix some project configuration
* fix linux build
* lsp: add lsp to PR artifacts and release assets
* lsp: address feedback
* fix typo
* more typo
* shorten discord rpc text
* allow expanding enums after the fact (untested)
* make `game_text` work similar to subtitles
* update progress decomp
* update some types + `do-not-decompile` in bitfield
* fixes and fall back to original progress code
* update `progress` decomp with new enums
* update config files
* fix enums and debug menu
* always allocate (but not use) a lot of particles
* small rework to display mode options
* revert resolution/aspect-ratio symbol mess
* begin the override stuff
* make `progress-draw` more readable
* more fixes
* codacy good boy points
* first step overriding code
* finish progress overrides, game options menu fully functional!
* minor fixes
* Update game.gp
* Update sparticle-launcher.gc
* clang
* change camera controls text
* oops
* some cleanup
* derp
* nice job
* implement menu scrolling lol
* make scrollable menus less cramped, fix arrows
* make some carousell things i guess
* add msaa carousell to test
* oops
* Update progress-pc.gc
* make `pc-get-screen-size` (untested)
* resolution menu
* input fixes
* return when selecting resolution
* scroll fixes
* Update progress-pc.gc
* add "fit to screen" button
* bug
* complete resolutions menu
* aspect ratio menu
* subtitles language
* subtitle speaker
* final adjustments
* ref test
* fix tests
* fix ref!
* reduce redundancy a bit
* fix mem leaks?
* save settings on progress exit
* fix init reorder
* remove unused code
* rename goal project-like files to the project extension
* sha display toggle
* aspect ratio settings fixes
* dont store text db's in compiler
* properly save+load native aspect stuff
* bug & crash fixes
* relax fog hack slightly
* buff particles more
* borderless hack
* tone down sprite hack
* int consts in `deftype` + increase sparticle queue
* move a menu button around
* clang + test fixes
* less confusing image
* add test for new deftype feature
* a crapton of fixes
* Update cavecrystal-light.gc
* damn you
* fix bunnies
* change codegen for int -> float cast (just add sign extension now)
* fix test
* this file is tagged anyway
* fix some stack types
* remove bad camera debug funcs
* add more heap bars and entity pick menu
* finish entity menu and make `music-flava` enum
* fix some `process-taskable` fields
* citadel sage crash fix
* fix citadel drop plats
* fix tests
* fix some casts
* update refs
* finish `village3-obs` and `snow-ball`
* Update README.md
* fix sidekick too
* fix issue?
* more entity inspect hardcoded checks
* more
* use `*display-actor-anim*` for something!
* CRAP
* also clear actor anim when deselecting entity
* *display-actor-anim* already renders this!
* do not display `path` tag info
* entity debug inspect tool
* one more
* make debug string even larger
* missing res tag types
* more polish and more known tags
* last few
* also add a new sprite renderer
* claaaang
* goal build fix
* fix tests, add stack singleton option
* make all event-message-blocks the same
* diskboot
* update jak 2 config and hack to make game text dumpable
* update stuff
* update src
* do `cspace<-parented-transformq-joint!`
* progress.... kind of...
* more drawable stuff
* clagng
* bones begin
* more bones
* even more bones
* everything builds
* touches
* errors
* ?
* fix `quicksandlurker`
* updates
* update refs
* more fixes
* update refs
* decomp `fisher`, `robotboss`, `light-eco`, `green-eco-lurker`, `sage-finalboss`, `robotboss-weapon`, `robotboss-misc`
* fixes
* add files
* add `:states` list to `deftype` and fix files
* test state forward decl's on a few more types
* also the refs
* add light-eco
* whatever
* change type of `seconds`
* fixes to pc pad input (visual only)
* strip down openGL to the version we're actually using for now (4.3 no extensions)
* turn on this opengl message
* really minor inconsequential change
* `flying-lurker`
* why'd this get left behind?
* also `ambient` and add a `banned_objects` config and fix offline tests
* clang
* fix `ambient-type-sound`
