{"id":15722578,"url":"https://github.com/astrochili/defold-illumination","last_synced_at":"2025-05-06T20:44:23.932Z","repository":{"id":57706694,"uuid":"516551377","full_name":"astrochili/defold-illumination","owner":"astrochili","description":"Ready-to-use forward shading lighting extension for Defold","archived":false,"fork":false,"pushed_at":"2025-02-02T22:52:17.000Z","size":1611,"stargazers_count":45,"open_issues_count":8,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T05:15:22.124Z","etag":null,"topics":["3d","defold","forward-shading","lighting"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astrochili.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-21T23:39:54.000Z","updated_at":"2025-03-26T18:58:02.000Z","dependencies_parsed_at":"2024-04-01T22:25:26.873Z","dependency_job_id":"408ff046-a453-43ef-9cbb-28a0a889256a","html_url":"https://github.com/astrochili/defold-illumination","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-illumination","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-illumination/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-illumination/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-illumination/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astrochili","download_url":"https://codeload.github.com/astrochili/defold-illumination/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252769017,"owners_count":21801373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","defold","forward-shading","lighting"],"created_at":"2024-10-03T22:08:28.965Z","updated_at":"2025-05-06T20:44:23.885Z","avatar_url":"https://github.com/astrochili.png","language":"Lua","funding_links":["https://buymeacoffee.com/astrochili"],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![logo](https://user-images.githubusercontent.com/4752473/185670169-8b27dcab-a6a9-4a9d-b1a7-ab4b136fdd65.jpg)\n\n# Illumination\n\n[![Release](https://img.shields.io/github/v/release/astrochili/defold-illumination.svg?include_prereleases=\u0026sort=semver\u0026color=blue)](https://github.com/astrochili/defold-illumination/releases)\n[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/astrochili/defold-illumination/blob/master/LICENSE)\n[![Website](https://img.shields.io/badge/website-gray.svg?\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxOCIgaGVpZ2h0PSIxNiIgZmlsbD0ibm9uZSIgdmlld0JveD0iMCAwIDE4IDE2Ij48Y2lyY2xlIGN4PSIzLjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYSkiLz48Y2lyY2xlIGN4PSI4LjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYikiLz48Y2lyY2xlIGN4PSIxMy42NSIgY3k9IjE0Ljc1IiByPSIxLjI1IiBmaWxsPSJ1cmwoI2MpIi8+PHBhdGggZmlsbD0idXJsKCNkKSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNNy42MyAxLjQ4Yy41LS43IDEuNTUtLjcgMi4wNSAwbDYuMjIgOC44MWMuNTguODMtLjAxIDEuOTctMS4wMyAxLjk3SDIuNDRhMS4yNSAxLjI1IDAgMCAxLTEuMDItMS45N2w2LjIxLTguODFaIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiLz48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIHgxPSIyLjQxIiB4Mj0iMi40MSIgeTE9IjEzLjUiIHkyPSIxNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRDhENDIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGOTU0MUYiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9IjcuNDEiIHgyPSI3LjQxIiB5MT0iMTMuNSIgeTI9IjE2IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agc3RvcC1jb2xvcj0iI0ZEOEQ0MiIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI0Y5NTQxRiIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJjIiB4MT0iMTIuNCIgeDI9IjEyLjQiIHkxPSIxMy41IiB5Mj0iMTYiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBzdG9wLWNvbG9yPSIjRkQ4RDQyIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjRjk1NDFGIi8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImQiIHgxPSIuMDMiIHgyPSIuMDMiIHkxPSIuMDMiIHkyPSIxMi4yNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRkU2NUUiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkM4MzAiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4=)](https://astronachos.com/)\n[![Mastodon](https://img.shields.io/badge/mastodon-gray?\u0026logo=mastodon)](https://mastodon.gamedev.place/@astronachos)\n[![Twitter](https://img.shields.io/badge/twitter-gray?\u0026logo=twitter)](https://twitter.com/astronachos)\n[![Telegram](https://img.shields.io/badge/telegram-gray?\u0026logo=telegram)](https://t.me/astronachos)\n[![Buy me a coffee](https://img.shields.io/badge/buy_me_a_coffee-gray?\u0026logo=buy%20me%20a%20coffee)](https://buymeacoffee.com/astrochili)\n\n📼 Also in this series:\n- 👖 [Kinematic Walker](https://github.com/astrochili/defold-kinematic-walker)\n- 🎥 [Operator](https://github.com/astrochili/defold-operator)\n- 🏗️ [TrenchFold](https://github.com/astrochili/defold-trenchfold)\n- 🚧 [Blockout Textures](https://github.com/astrochili/blockout-textures)\n\n## Overview\n\nThis extension contains ready-to-use forward shading lighting for 3D games made with Defold. Just set the provided material to your mesh and place light sources on the scene.\n\nTechnically it supports about ~200 light sources, but the performance limit is about 20-30 sources at the moment. Need to implement [clustered forward shading](https://github.com/astrochili/defold-illumination/issues/1) to get a valuable performance boost.\n\nAll the lighting data passed to the shader program as the texture, so it doesn't use a render script.\n\n🎮 [Play HTML5 demo](https://astronachos.com/defold/illumination) with 🔦 on the `E` key.\n\n💬 [Discuss on the forum](https://forum.defold.com/t/illumination-ready-to-use-forward-shading-lighting-for-3d-games/71465/2).\n\n## Features\n\n- [x] Linear and radial fog.\n- [x] Ambient lighting.\n- [x] Directional lighting.\n- [x] Light points and spots.\n- [x] Everything can be animated with `go.animate()`.\n- [x] Support for baked light maps (also can be used as emission maps).\n- [x] Support for specular maps.\n- [x] Support for normal maps.\n- [ ] [Support for height maps](https://github.com/astrochili/defold-illumination/issues/2).\n- [ ] [Clustered forward shading](https://github.com/astrochili/defold-illumination/issues/1).\n- [ ] Request by [adding an issue or contribute](https://github.com/astrochili/defold-illumination/issues).\n\n## Install\n\nAdd link to the zip-archive of the latest version of [defold-illumination](https://github.com/astrochili/defold-illumination/releases) to your Defold project as [dependency](http://www.defold.com/manuals/libraries/).\n\n## Quick Start\n\n1. Add `illumination.go` to your scene as the sunlight source and configure it.\n2. Add `light_point.go` or `light_spot.go` as light sources and configure them.\n3. Set `/illumination/materials/model.material` to your mesh.\n4. Set `/illumination/textures/data.png` to the *`DATA_TEXTURE`* slot.\n5. Fill *`LIGHT_TEXTURE`*, *`SPECULAR_TEXTURE`* and *`NORMAL_TEXTURE`* slots with your maps or set the empty texture `/illumination/textures/empty.png`.\n\n## Illumination\n\n![illumination](https://user-images.githubusercontent.com/4752473/185738458-fdac06c0-275f-4dae-a0a2-c55335e9bd13.jpg)\n\n### rotation\n\nAffects the direction of sunlight.\n\n### ambient_color\n\nAmbient light color.\n\n### ambient_level\n\nAmbient light strength from `0.0` to `1.0`.\n\n### sunlight_color\n\nDirectional light color.\n\n### sunlight_brightness\n\nDirectional light strength from `0.0` to `1.0`.\n\n### sunlight_specular\n\nDirectional light specular component from `0.0` to `1.0`.\n\n### fog\n\nAdds fog in front of the camera and fade-out distant objects.\n\n### fog_is_radial\n\n- `true` — calculates the fog around the camera position.\n- `false` — calculates the fog along the camera view direction.\n\n### fog_distance_min\n\nDistance at which the fog begins to appear.\n\n### fog_distance_max\n\nDistance at which the fog reaches the full strength.\n\n### fog_color\n\nUsed to draw the fog gradient and sent with the `clear_color` message to the render script.\n\n### fog_level\n\nFog full strength from `0.0` to `1.0`.\n\n- `1.0` — not a transparent fog. It can save some performance by ignoring the lighting calculation.\n\n## Light\n\n![light-point](https://user-images.githubusercontent.com/4752473/185738463-5b5deabb-817b-4996-be2c-2828efada7bf.jpg)\n![light-spot](https://user-images.githubusercontent.com/4752473/185738462-79790471-b315-4d40-8352-4751d1492b53.jpg)\n\nThere are `light_point.go` and `light_spot.go`. The only difference is the texture of the debug mesh for a friendlier placement on the scene.\n\n### position\n\nLight source world position.\n\n### rotation\n\nRotation affects the direction of the spotlight when [`cutoff`](#cutoff) is less than `1.0`.\n\n### color\n\nLight color that will be multiplied with the diffuse color.\n\n### brightness\n\nLight brightness from `0.0` to `1.0`.\n\n- `0.0` — turn off to save some performance by ignoring the lighting calculation.\n- `1.0` — full brightness.\n\n### radius\n\nLight radius.\n\n- `0.0` — turn off to save some performance by ignoring the lighting calculation.\n\n### specular\n\nLight specular component from `0.0` to `1.0`, will be multiplied with the specular map color.\n\n### smoothness\n\nLight smoothness / attenuation from `0.0` to `1.0`.\n\n- `0.0` — no attenuation at all, fill all the radius evenly.\n- `1.0` — standard attenuation from the center to the edges.\n\n### cutoff\n\nSpotlight cutoff from `0.0` to `1.0`.\n\n- `0.0` — no light.\n- `0.3` — like a flashlight.\n- `0.5` — half of the sphere.\n- `1.0` — no cutoff.\n\nTo get the best results, you need to jungle with [`radius`](#radius), [`cutoff`](#cutoff) and [`smoothness`](#smoothness), which is [not so obvious](https://github.com/astrochili/defold-illumination/issues/4) at the moment.\n\n## Material\n\n![material](https://user-images.githubusercontent.com/4752473/185738654-0bdd5e6d-0f90-47ad-b52b-cf1cf5d561c5.jpg)\n![flashlight](https://user-images.githubusercontent.com/4752473/185738460-0c66e9fd-99c2-4001-a2ac-e29bcc54836c.jpg)\n\nUse the `/illumination/materials/model.material` material on your meshes to add them to lighting calculation.\n\nIt's important to fill unused texture slots with `/illumination/textures/empty.png`.\n\n### DIFFUSE_TEXTURE\n\nA basic diffuse texture.\n\n### DATA_TEXTURE\n\nThe illumination data texture, always set to `/illumination/textures/data.png`.\n\n### LIGHT_TEXTURE\n\nA baked light map or an emission map texture.\n\n- `/illumination/textures/white.png` to have full strength emmission.\n- `/illumination/textures/empty.png` to skip it.\n\nIf your light map texture has different uv coordinates from the diffuse texture you need to turn on [surface.y](#surface) constant.\n\n### SPECULAR_TEXTURE\n\nA specular map texture.\n\n- `/illumination/textures/white.png` to have full strength reflection.\n- `/illumination/textures/empty.png` to skip it.\n\n### NORMAL_TEXTURE\n\nA normal map texture with green on the top.\n\n- `/illumination/textures/empty.png` to skip it.\n\nOpenGL normal maps format used by default. To use DirectX format turn on [surface.z](#surface) constant.\n\n### surface\n\nFragment constant to pass some surface properties.\n\n- `x` — the surface shininess. Impacts the scattering of the specular highlight. Default value is `32.0`.\n- `y` — using separate uvs for the light map. Set to `1.0` to use the stream `texcoord1` as light map uv coordinates. By default it's `0.0` and uses the `texcoord0` stream.\n- `z` — use the OpenGL or DirectX normal maps format. Set to `1.0` to use DirectX format where green is down. By default it's `0.0` and uses the OpenGL format where green is top.\n\n## Module\n\n### illumination.set_debug(is_enabled)\n\nEnables the sun and light sources debug meshes.\n\n```lua\nillumination.set_debug(true)\n```\n\n### illumination.is_debug()\n\nReturns the debug mode state as boolean.\n\n```lua\nlocal is_debug = illumination.is_debug()\n```\n\n### illumination.set_light(light, url)\n\nManually add or remove a light source. Don't use it if you already use `light_point.go` or `light_spot.go`.\n\n\n```lua\n-- Prepare the light\nlocal light = {\n    position = go.get_world_position(),\n    direction = vmath.rotate(go.get_world_rotation(), vmath.vector3(0, 0, 1)),\n    color = vmath.vector4(1.0),\n    radius = 5.0,\n    specular = 0.5,\n    smoothness = 1.0,\n    cutoff = 1.0,\n}\n\n-- Prepare the url\nlocal light_url = msg.url('#')\n\n-- Add or update the light\nillumination.set_light(light, light_url)\n\n-- Remove the light\nillumination.set_light(nil, light_url)\n```\n\n## TrenchBroom\n\n[TrenchFold](https://github.com/astrochili/defold-trenchfold#illumination-light_point-light_spot) extension contains entities `illumination`, `light_point` and `light_spot` to configure lighting directly on the map.\n\nTo assign textures to meshes use [texture path patterns](https://github.com/astrochili/defold-trenchfold#texture-path-patterns):\n\n- `texture1` — `/illumination/textures/data.png`\n- `texture2` — `*_light.png` or `/illumination/textures/empty.png`\n- `texture3` — `*_specular.png` or `/illumination/textures/empty.png`\n- `texture4` — `*_normal.png` or `/illumination/textures/empty.png`\n\n## Credits\n\n- Textures in the demo are from Tiny Texture Pack [1](https://screamingbrainstudios.itch.io/tiny-texture-pack)-[2](https://screamingbrainstudios.itch.io/tiny-texture-pack-2) by [Screaming Brain Studios](https://screamingbrainstudios.itch.io/).\n- Specular and normal maps generated with [Normal Map Online](https://cpetry.github.io/NormalMap-Online/) by [@cpetry](https://github.com/cpetry).\n- The header background picture by [Thor Alvis](https://unsplash.com/photos/sgrCLKYdw5g).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-illumination","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrochili%2Fdefold-illumination","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-illumination/lists"}