Skip to content

feat(lua): Lua Tile Rendering#8048

Draft
AzmodiusX wants to merge 11 commits intocataclysmbn:mainfrom
AzmodiusX:Lua_Tiles
Draft

feat(lua): Lua Tile Rendering#8048
AzmodiusX wants to merge 11 commits intocataclysmbn:mainfrom
AzmodiusX:Lua_Tiles

Conversation

@AzmodiusX
Copy link
Copy Markdown
Collaborator

@AzmodiusX AzmodiusX commented Feb 5, 2026

Purpose of change (The Why)

Lua could use some additional help with rendering tiles. We have hard-coded graphical effects for stuff like explosions, projectiles, etc... Why not Lua?

blocked by #8336

Describe the solution (The How)

Implements a (hopefully) robust tile rendering system with handles and 2 layers of cleanup; Time based and reality bubble based.

Describe alternatives you've considered

Really awkward stuff like spawning and de-spawning NPCs with effects or mutations on them where I want to render stuff.

Testing

local tint = TintConfig.new("#ff0000")
tint:set_blend_mode("overlay")
local pair = TintPair.new(tint)

--[[ Use this for one tile test
local player = gapi.get_avatar()
local map = gapi.get_map()
local pos = map:get_abs_ms(player:get_pos_ms())
gapi.add_lua_tile("t_wall", pair, pos, 10)
]]

-- Use this for snek test
local on_player_move = function(params)
	local player = params.player
	local map = gapi.get_map()
	local abs_pos = map:get_abs_ms(params.from)
	local h = gapi.add_lua_tile("t_wall", pair, abs_pos, 10)
end

game.add_hook("on_player_try_move", function(...) return on_player_move(...) end)

Will render neat snek
Observe:
cataclysm-bn-tiles_3ci3jxsdLl
IrDn5nhVDz
LkdY8keV25
Tinted:
image

Additional context

It doesn't render where you don't have vision.
Effects light shadow effect the tiles.
I did my best to ensure the performance impact wouldn't be too bad even if the mod author plays a bit fast and loose.
Removes tiles that go outside of the reality bubble.
Clears them on game load. They don't get saved, so there's no point in keeping them around. It's up to the mod author to account for this.
While the duration can be set to -1 for permanent, the docs give a fair warning about performance, and the default duration is 1 turn.
Now that #8026 was merged, I can implement standardized tinting behavior.
Currently, you can:
Remove by handle
Remove at position
Clear everything

Considerations

Perhaps this needs to seperate tiles by mod_id so clear_everything doesn't break other mods stuff?
Unsure, since there are so many other ways to do this responsibly on the Lua side.

@github-actions github-actions Bot added src changes related to source code. lua PRs and issues related to Lua scripting labels Feb 5, 2026
@autofix-ci
Copy link
Copy Markdown
Contributor

autofix-ci Bot commented Feb 5, 2026

Autofix has formatted code style violation in this PR.

I edit commits locally (e.g: git, github desktop) and want to keep autofix
  1. Run git pull. this will merge the automated commit into your local copy of the PR branch.
  2. Continue working.
I do not want the automated commit
  1. Format your code locally, then commit it.
  2. Run git push --force to force push your branch. This will overwrite the automated commit on remote with your local one.
  3. Continue working.

If you don't do this, your following commits will be based on the old commit, and cause MERGE CONFLICT.

AzmodiusX and others added 3 commits February 8, 2026 19:34
Allows lua to declare color_tint_pairs and tint_configs
Tiles can now be tinted
Declared tint_config and color_tint_pair lua types
@github-actions github-actions Bot added the docs PRs releated to docs page label Feb 14, 2026
@AzmodiusX AzmodiusX marked this pull request as ready for review February 15, 2026 01:30
Better Docs
Added a few more conversions
@github-actions github-actions Bot removed the docs PRs releated to docs page label Feb 15, 2026
@AzmodiusX AzmodiusX marked this pull request as draft April 4, 2026 11:59
@AzmodiusX
Copy link
Copy Markdown
Collaborator Author

Deferred for SDL3 since this didn't pick up much traction before. I'm not binning anything, no worries.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lua PRs and issues related to Lua scripting src changes related to source code.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant