ppy/osu-framework

Documentation tasks

smoogipoo opened this issue · 24 comments

smoogipoo commented

This is a permanent issue where we will list areas of the framework that need better documentation. Feel free to tackle these tasks if you have time.

XMLDoc improvements

TooltipContainer

  • The reuse of tooltips.
  • The reuse of custom tooltips, on a per-type basis, and how to avoid re-use.
  • How content is passed from Drawable to a custom tooltip (TooltipContent / SetContent()).

Drawable

  • DrawSize does not account for scale of either the Drawable itself or any of its parents.
  • DrawScale does not account for scale of parents.
  • End event handler methods (e.g. OnKeyUp, OnFocusLost, etc...) need rewording to better indicate which requires handling begin event. #3625 (comment)

Wiki documentation

We hope to add more auxiliary documentation on the wiki covering common patterns in the framework. If you wish to contribute to this (and don't have access) please feel free to post an article in this thread and we will transfer it across.

Drawables

Layout

  • How coordinates systems work (and relative sizing)
  • How to use DrawSizePreservingFillContainer to make custom coordinate spaces (and aspect ratio enforcement) for hierarchies
  • How anchor / origin work (can be roughly transferred from my blog post source)

Event handling

  • When drawables receive end events must be mentioned correctly. #3625 (comment)

Fonts

Debugging

TimOliver commented

Here's what I've got for the layout system so far: https://github.com/ppy/osu-framework/wiki/Coordinate-and-Layout-System

  • 👍2
  • ❤️1
bdach commented

@TimOliver FYI I can't actually see any text there; think it might only be visible to you at this point (probably stored locally browser-side).

TimOliver commented

@bdach Ah, I renamed the page title. I didn't realise the old URLs don't automatically redirect. I updated it now! :)

  • 👍1
frenzibyte commented

Finished up the Font section:

  • Converting to binary font with texture files
  • Adding font resources to the game
  • Using font for a sprite text with FontUsage (probably important for specifying what font to use)

Published to the osu!framework wiki: https://github.com/ppy/osu-framework/wiki/Setting-Up-Fonts

  • 👍2
  • ❤️1
Coppertine commented

@iiSalman You need to spesify that all BMFont files are safed as fnt where as osu!framework can only read .bin, you have to change the extension first. You can write .bin in the save as window as it would just so MyAwesomeFont.bin.font and MyAwesomeFont.bin-0.png respectively

frenzibyte commented

well, fun fact: osu!framework reads both .bin and .fnt (check FontStore.cs), so it's unnecessary to do that IMO, maybe leaving a note saying it may be better to change the extension to .bin as the font is of binary data for your collaborators not to confuse it with text / XML descriptors, will do that. Nevermind, the font itself starts with the magic string FNT anyways.

Redageddon commented

One of the biggest things that is needed is, how do screen transitions work. For example: How do I open screen A and close screen B. This cannot be inferred from osu!lazer and osu!framework doesn't have documentation on how to make something like that

Redageddon commented

I don't even mean specifically for 'Screen'. I just mean, more explanation could be given on how to, lets say, show a beatmap selection screen when a button is pressed in main menu

frenzibyte commented

Isn't https://github.com/ppy/osu-framework/wiki/Screens-and-Screen-Stacks what you're looking for to read? sounds like you're looking for a method to "open" a screen (technically pushes it to the screen stack)

frenzibyte commented

Please elaborate more on what you need, the above page talks about screen and screen stacks, which (from what you're asking above) seemingly answers your question.

Redageddon commented

what I meant was, how to handle multiple screens. It doesn't tell you how to go back and forth between scenes and how not to create multiple screen instances and things along those lines. The link you sent only has 2 examples and that is how to setup the stack, not how to properly use it.

Redageddon commented

Like it doesn't explain how to not have multiple screen instances, it just has the things for entering, exiting, resuming and suspending

peppy commented

You should be able to have multiple screen instances. Am I understanding your issue incorrectly? Screens are the most heavily documented and tested classes of the whole framework so I'm interested to know what error / issue you came across.

Redageddon commented

I am just trying to figure out how things work in the framework. Like if i set up a screen how do I switch between screens? Are scenes stacked on top of each other or do they open like how unity scenes work? Should there be a single thing holding all scenes that you switch though or should you open a new screen based on the one you open? -- These (this is not all, just a few examples) are the types of questions that are not answered very well. Either by reading xmldocs or looking at how osu!lazer wokrs

peppy commented

i guess the structure of screens was assumed to be conveyed by the class name "ScreenStack".

Redageddon commented

I could infer that, but not how to use it fully or how to use it correctly.

peppy commented

Have you checked out the visual tests project, which has example usages for each component? Can you explain what part of https://github.com/ppy/osu-framework/wiki/Screens-and-Screen-Stacks is not clear? This mentions how to push, exit and the general concept of the screen stack. It seems to cover everything you've mentioned.

Redageddon commented

I have read that, but I didn't get much out of it.

Redageddon commented

It shows how you would handle it in one area, not a project type of setting.

Redageddon commented

https://github.com/Quaver/Wobble is a good example of the type of framework documentation i was meaning.

peppy commented

I'm not even sure what you're expecting. That page has very little documentation. We have several sample projects which are heavily documented, a full wiki which should have everything you need to get started, and visual tests covering each component in various scenarios.

The screen stack page already explains how to use it.

I would suggest the next step is that you rewrite the screen stack documentation in a way you'd expect it to be presented so we can assess it.

Redageddon commented

Wait, where are the sample projects, besides for the flappy bird one, i haven't been able to find any. Also i would like to apologize if i am coming across as rude, i'm not trying to be, but i know that i can get that way sometimes.

peppy commented

FlappyBird is the most complete example, alongside the empty game project: https://github.com/ppy/osu-framework/wiki/Setting-up-your-first-project

Visual tests can be observed in the huge VisualTests project of the framework itself. You can run it directly after cloning the framework (it should be the default run configuration after a fresh clone), and it comes with hundreds of examples that you can interact with.