beyond-all-reason / beyond-all-reason/RecoilEngine
Document what is CUS and how to use it
- Dominant language
- C++
- Stars
- 683
- Forks
- 293
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 40
Description
CUS is the ability for games to customize the shading of world objects such as units and features.
Currently this technology is used in some way or another by games such as BAR or ZK, with gl4 feature support. While other games might use older CUS support.
We need to make clear what's the purpose and what entails implementing CUS. Additionally, apart from the lack of documentation, there's no game agnostic template for new games to implement it or for non gl4 CUS games to migrate.
Task is 2-fold, one required and an optional but nice-to-have task:
- Page describing exactly what CUS is supposed to be, and be implemented, in a way a game developer can have the insight to at least get started on the most approachable aspects of this endeavour (disabling engine hardcoded rendering, what exactly needs to be wired up in terms of callins and draw calls, gotchas, etc)
- Widget/Gadget/Code snippet that implements a basic template that is good for most simple games, and even when not necessarily plug-and-play, provides for - via simplicity and readability of code - a good framework to work with a few modifications.
### References
Close attention to drawflag passing to worldobjects (to turn off default engine rendering at specific passes), callins to manage state and callins to draw.
- GL3 Implementation: https://github.com/SpringMCLegacy/SpringMCLegacy/blob/4b5c9ad/LuaRules/Gadgets/gfx_customUnitShaders.lua
- GL4 Implementations
- https://github.com/ZeroK-RTS/Zero-K/blob/e79e548/LuaRules/Gadgets/gfx_commander_skins.lua
- https://github.com/beyond-all-reason/Beyond-All-Reason/blob/c086c83/luarules/gadgets/cus_gl4.lua
#### Discussion
(on the matter of complexity to develop gl4 cus)
> There're two big tasks:
> - Handle the changes in the unit visbility state and reflect these changes in the VAO commands
> - Bin units by FFP variants. E.g. by the textures they use, or shader types or anything like this
> Once these two big tasks are accomplished, the rest is pretty trivial.
> Basically all models data sit on the GPU permanently in a few big memory buffers. Thus it's possible to render everything in one go. Very efficient.
> The unfortunate part is that "one go" is only as long as the aforementioned bin
> So if you have a texture per model, that bin can only contain the units of that type
> With a texture per faction, we can render all faction units
Contributor guide
Research direction
Start with the referenced LuaRules/Gadgets/gfx_customUnitShaders.lua, gfx_commander_skins.lua, and luarules/gadgets/cus_gl4.lua implementations. Compare their drawflag passing, state-management callins, and draw callins to identify the common CUS concepts and migration gotchas. Done means a game-agnostic explanatory page and, if pursued, a readable basic template for new or non-GL4 CUS games.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- lua
- Domain
- computer-graphics, documentation, game-dev
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100