Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (30 loc) · 3.21 KB

AGENTS.md

File metadata and controls

48 lines (30 loc) · 3.21 KB
Raw

Setup commands

  • compile: make
  • run particular tests: GTEST_FILTER=SomeTest.* make tests-yourmodulename-run
  • run ui based tests like this: UI_TESTFILTER=XXX make tests-voxedit-run. To get a list of the available tests, run this before: build/voxedit/vengi-tests-voxedit --imgui_list_tests. To run all tests, just omit the UI_TESTFILTER env var. (See ImGuiTestEngine_PassFilter for a description of the filters)
  • run all tests: make tests
  • check the documentation under docs if your change would also require the documentation to be updated (or extended)

Code style

  • try to avoid the STL where possible! - no exceptions, no rtti, C-style casts.

General

  • when touching code, ensure that a test is written for it - if not, write one to test the change - and execute that test
  • all vengi tools understand the --help parameter to print the usage for command line parameters
  • don't add unicode characters in comments or code - only ascii
  • When doing rendering code changes, check if a visual test in src/tests exists and implement one. If a tests exists, you can you --screenshot 5 to generate a screenshot after 5 frames of lifetime. In combination with xvfb-run on linux, you can get the rendering result in a screenshot to inspect.

Logging

  • when adding debug logging via Log::debug(), make sure to use the environment variable CORE_LOGLEVEL=2 in front of your vengi applications or your make calls.

Shaders

  • the glsl shader C++ code is autogenerated by a tool called shadertool - see docs/ShaderTool.md for more details on how to use it. This is crucial when you are creating or updating shaders. The source code is in the build directory in a directory called generated/shaders/<module>. Also uniform data C++ structs are auto generated. You have to run make as described above each time you modify a shader.

LUA Scripts

  • more details on the lua scripts and the api can be found here: docs/LUAScript.md and the docs/lua folder - if you are extending or modifying the api, make sure to also keep the documentation in sync - by providing the _jsonhelp function, too.
  • docs/lua is autogenerated by make lua-api in the project root Makefile helper
  • if you add new lua scripts, make sure to add them to the lua api test suite that is executing the scripts and reports errors.
  • always try to make your scripts reusable by not hardcoding important values, but implementing them as arguments.
  • if installed, run luacheck --codes . in the directory src

Scenegraph

  • to get scenegraph details you can use vengi-voxconvert --json all --input thefile.ext - all, palette, meshdetails, nodedetails, children, palettematerials, animations are all valid --json parameters. Use vengi-voxconvert --help to get more details.

Colors

When inspecting colors from palettes, you can use vengi-palconvert --input thefile --type json to get the colors listed. Also as for the other tools - check out vengi-palconvert --help if your task is about colors.

If you need to do this on a non-palette format, you can use voxconvert here, too: vengi-voxconvert --input thefile --json palette,children

Git workflow

Always use a git worktree while starting a refactoring to not pollute the workspace for others.