docs: improve light entity documentation
This commit is contained in:
Eric Wasylishen
parent
a5b77d4dc4
commit
06b5e6dc64
|
|
@ -1,2 +1,2 @@
|
|||
_build
|
||||
_html
|
||||
*html*
|
||||
|
|
|
|||
|
|
@ -39,6 +39,8 @@ templates_path = ['_templates']
|
|||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# report broken references
|
||||
nitpicky = True
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -54,6 +54,36 @@ def setup(app: Sphinx):
|
|||
indextemplate='pair: %s; light entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='spotlight-key',
|
||||
rolename='spotlight-key',
|
||||
indextemplate='pair: %s; spotlight entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='surflight-key',
|
||||
rolename='surflight-key',
|
||||
indextemplate='pair: %s; surface light entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='projlight-key',
|
||||
rolename='projlight-key',
|
||||
indextemplate='pair: %s; projected texture light entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='skylight-key',
|
||||
rolename='skylight-key',
|
||||
indextemplate='pair: %s; skylight entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='sunlight-key',
|
||||
rolename='sunlight-key',
|
||||
indextemplate='pair: %s; sunlight entity key',
|
||||
parse_node=parse_epair,
|
||||
)
|
||||
app.add_object_type(
|
||||
directivename='classname',
|
||||
rolename='classname',
|
||||
|
|
|
|||
215
docs/light.rst
215
docs/light.rst
|
|
@ -790,7 +790,7 @@ If used on func_detail* or func_group, a full qbsp pass need to be run.
|
|||
Integer. Default 0.
|
||||
|
||||
Can be set to a nonzero value to make these brushes emit as surface lights
|
||||
only from a light template with a matching :light-key:`_surflight_group` value.
|
||||
only from a light template with a matching :surflight-key:`_surflight_group` value.
|
||||
|
||||
.. bmodel-key:: "_lightcolorscale" "n"
|
||||
|
||||
|
|
@ -805,6 +805,9 @@ Light entity keys can be used in any entity with a classname starting
|
|||
with the first five letters "light". E.g. "light", "light_globe",
|
||||
"light_flame_small_yellow", etc.
|
||||
|
||||
Point Lights
|
||||
------------
|
||||
|
||||
.. light-key:: "light" "n"
|
||||
|
||||
Set the light intensity. Negative values are also allowed and will
|
||||
|
|
@ -821,7 +824,7 @@ with the first five letters "light". E.g. "light", "light_globe",
|
|||
|
||||
Select an attenuation formaula for the light:
|
||||
|
||||
::
|
||||
.. code:: none
|
||||
|
||||
0 => Linear attenuation (default)
|
||||
1 => 1/x attenuation
|
||||
|
|
@ -850,30 +853,6 @@ with the first five letters "light". E.g. "light", "light_globe",
|
|||
light. RGB component values are between 0 and 255 (between 0 and 1 is
|
||||
also accepted). Default is white light ("255 255 255").
|
||||
|
||||
.. light-key:: "target" "name"
|
||||
|
||||
Turns the light into a spotlight, with the direction of light being
|
||||
towards another entity with it's "targetname" key set to "name".
|
||||
|
||||
.. light-key:: "mangle" "yaw pitch roll"
|
||||
|
||||
Turns the light into a spotlight and specifies the direction of light
|
||||
using yaw, pitch and roll in degrees. Yaw specifies the angle around
|
||||
the Z-axis from 0 to 359 degrees and pitch specifies the angle from
|
||||
90 (straight up) to -90 (straight down). Roll has no effect, so use
|
||||
any value (e.g. 0). Often easier than the "target" method.
|
||||
|
||||
.. light-key:: "angle" "n"
|
||||
|
||||
Specifies the angle in degrees for a spotlight cone. Default 40.
|
||||
|
||||
.. light-key:: "_softangle" "n"
|
||||
|
||||
Specifies the angle in degrees for an inner spotlight cone (must be
|
||||
less than the "angle" cone. Creates a softer transition between the
|
||||
full brightness of the inner cone to the edge of the outer cone.
|
||||
Default 0 (disabled).
|
||||
|
||||
.. light-key:: "targetname" "name"
|
||||
|
||||
Turns the light into a switchable light, toggled by another entity
|
||||
|
|
@ -921,7 +900,49 @@ with the first five letters "light". E.g. "light", "light_globe",
|
|||
Number of lights to use for "_deviance". Default 16 (only used if
|
||||
"_deviance" is set).
|
||||
|
||||
.. light-key:: "_surface" "texturename"
|
||||
.. light-key:: "_bouncescale" "n"
|
||||
|
||||
Scales the amount of light that is contributed by bounces. Default is
|
||||
1.0, 0.0 disables bounce lighting for this light.
|
||||
|
||||
.. light-key:: "_nostaticlight" "n"
|
||||
|
||||
Set to 1 to make the light compiler ignore this entity (prevents it
|
||||
from casting any light). e.g. could be useful with rtlights.
|
||||
|
||||
Spotlights
|
||||
----------
|
||||
|
||||
Supports all keys from `Point Lights`_ in addition to the following:
|
||||
|
||||
.. spotlight-key:: "target" "name"
|
||||
|
||||
Turns the light into a spotlight, with the direction of light being
|
||||
towards another entity with it's "targetname" key set to "name".
|
||||
|
||||
.. spotlight-key:: "mangle" "yaw pitch roll"
|
||||
|
||||
Turns the light into a spotlight and specifies the direction of light
|
||||
using yaw, pitch and roll in degrees. Yaw specifies the angle around
|
||||
the Z-axis from 0 to 359 degrees and pitch specifies the angle from
|
||||
90 (straight up) to -90 (straight down). Roll has no effect, so use
|
||||
any value (e.g. 0). Often easier than the "target" method.
|
||||
|
||||
.. spotlight-key:: "angle" "n"
|
||||
|
||||
Specifies the angle in degrees for a spotlight cone. Default 40.
|
||||
|
||||
.. spotlight-key:: "_softangle" "n"
|
||||
|
||||
Specifies the angle in degrees for an inner spotlight cone (must be
|
||||
less than the "angle" cone. Creates a softer transition between the
|
||||
full brightness of the inner cone to the edge of the outer cone.
|
||||
Default 0 (disabled).
|
||||
|
||||
Surface Lights
|
||||
--------------
|
||||
|
||||
.. surflight-key:: "_surface" "texturename"
|
||||
|
||||
Makes surfaces with the given texture name emit light, by using this
|
||||
light as a template which is copied across those surfaces. Lights are
|
||||
|
|
@ -929,118 +950,160 @@ with the first five letters "light". E.g. "light", "light_globe",
|
|||
apart and positioned 2 units above the surfaces.
|
||||
|
||||
To restrict this surface light config to a subset of brushes with
|
||||
the "texturename" texture applied, see the :light-key:`_surflight_group` key.
|
||||
the "texturename" texture applied, see the :surflight-key:`_surflight_group` key.
|
||||
|
||||
.. light-key:: "_surface_offset" "n"
|
||||
.. surflight-key:: "_surface_offset" "n"
|
||||
|
||||
Controls the offset lights are placed above surfaces for :light-key:`_surface`.
|
||||
Controls the offset lights are placed above surfaces for :surflight-key:`_surface`.
|
||||
Default 2.
|
||||
|
||||
.. light-key:: "_surface_spotlight" "n"
|
||||
.. surflight-key:: "_surface_spotlight" "n"
|
||||
|
||||
For a surface light template (i.e. a light with :light-key:`_surface` set),
|
||||
For a surface light template (i.e. a light with :surflight-key:`_surface` set),
|
||||
setting this to "1" makes each instance into a spotlight, with the
|
||||
direction of light pointing along the surface normal. In other words,
|
||||
it automatically sets "mangle" on each of the generated lights.
|
||||
|
||||
.. light-key:: "_surface_radiosity" "n"
|
||||
.. surflight-key:: "_surface_radiosity" "n"
|
||||
|
||||
Whether to use Q1-style surface subdivision (0) or Q2-style
|
||||
surface radiosity (1) on this light specifically.
|
||||
|
||||
Use in conjunction with :light-key:`_surface`.
|
||||
Use in conjunction with :surflight-key:`_surface`.
|
||||
|
||||
The default can be changed for all surface lights in a map with
|
||||
worldspawn key :worldspawn-key:`_surflight_radiosity`.
|
||||
|
||||
.. light-key:: "_surflight_group" "n"
|
||||
.. surflight-key:: "_surflight_group" "n"
|
||||
|
||||
Integer, default 0.
|
||||
|
||||
For use with :light-key:`_surface` lights.
|
||||
For use with :surflight-key:`_surface` lights.
|
||||
|
||||
Can be set to a nonzero value to restrict
|
||||
this surface light template to only emit from brushes with a matching
|
||||
:bmodel-key:`_surflight_group` value.
|
||||
|
||||
.. light-key:: "_project_texture" "texture"
|
||||
|
||||
Projected Texture Lights
|
||||
------------------------
|
||||
|
||||
.. projlight-key:: "_project_texture" "texture"
|
||||
|
||||
Specifies that a light should project this texture. The texture must
|
||||
be used in the map somewhere.
|
||||
|
||||
.. light-key:: "_project_mangle" "yaw pitch roll"
|
||||
.. todo:: This is a qbsp limitation which could be fixed
|
||||
|
||||
.. projlight-key:: "_project_mangle" "yaw pitch roll"
|
||||
|
||||
Specifies the yaw/pitch/roll angles for a texture projection
|
||||
(overriding mangle).
|
||||
|
||||
.. light-key:: "_project_fov" "n"
|
||||
.. projlight-key:: "_project_fov" "n"
|
||||
|
||||
Specifies the fov angle for a texture projection. Default 90.
|
||||
|
||||
.. light-key:: "_bouncescale" "n"
|
||||
|
||||
Scales the amount of light that is contributed by bounces. Default is
|
||||
1.0, 0.0 disables bounce lighting for this light.
|
||||
Sun Light
|
||||
---------
|
||||
|
||||
.. light-key:: "_sun" "n"
|
||||
Also called directional light. Emitted from sky faces.
|
||||
|
||||
.. sunlight-key:: "_sun" "n"
|
||||
|
||||
Set to 1 to make this entity a sun, as an alternative to using the
|
||||
sunlight worldspawn keys. If the light targets an info_null entity,
|
||||
sunlight worldspawn keys.
|
||||
|
||||
.. sunlight-key:: "target" "t"
|
||||
|
||||
If the light targets an info_null entity,
|
||||
the direction towards that entity sets sun direction. The light
|
||||
itself is disabled, so it can be placed anywhere in the map.
|
||||
|
||||
The following light properties correspond to these sunlight settings:
|
||||
.. sunlight-key:: "mangle" "yaw pitch roll"
|
||||
|
||||
::
|
||||
Alternate way of specifying sunlight direction.
|
||||
|
||||
light => _sunlight
|
||||
mangle => _sunlight_mangle
|
||||
deviance => _sunlight_penumbra
|
||||
_color => _sunlight_color
|
||||
_dirt => _sunlight_dirt
|
||||
_anglescale => _anglescale
|
||||
style => flicker style for styled sunlight
|
||||
targetname => targetname for switchable sunlight
|
||||
_suntexture => this sunlight is only emitted from faces with this texture name
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight_mangle`.
|
||||
|
||||
.. light-key:: "_sunlight2" "n"
|
||||
.. sunlight-key:: "light" "n"
|
||||
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight`.
|
||||
|
||||
.. sunlight-key:: "color" "r g b"
|
||||
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight_color`.
|
||||
|
||||
.. sunlight-key:: "deviance" "n"
|
||||
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight_penumbra`.
|
||||
|
||||
.. sunlight-key:: "_dirt" "n"
|
||||
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight_dirt`.
|
||||
|
||||
.. sunlight-key:: "_anglescale" "n"
|
||||
|
||||
Equivalent to worldspawn key :worldspawn-key:`_anglescale`.
|
||||
|
||||
.. sunlight-key:: "style" "n"
|
||||
|
||||
Flicker style for styled sunlight.
|
||||
|
||||
.. sunlight-key:: "targetname" "name"
|
||||
|
||||
Targetname for switchable sunlight.
|
||||
|
||||
.. sunlight-key:: "_suntexture" "texname"
|
||||
|
||||
This sunlight is only emitted from faces with this texture name. Default is to be emitted from all sky textures.
|
||||
|
||||
|
||||
Sky Light
|
||||
---------
|
||||
|
||||
Hemisphere shaped light emitted from sky faces.
|
||||
|
||||
.. skylight-key:: "_sunlight2" "n"
|
||||
|
||||
Set to 1 to make this entity control the upper dome lighting emitted
|
||||
from sky faces, as an alternative to the worldspawn key :worldspawn-key:`_sunlight2`.
|
||||
The light entity itself is disabled, so it can be placed anywhere in
|
||||
the map.
|
||||
|
||||
The following light properties correspond to these sunlight settings:
|
||||
.. skylight-key:: "_sunlight3" "n"
|
||||
|
||||
light
|
||||
_sunlight2
|
||||
Same as :skylight-key:`_sunlight2`, but makes this sky light come from the lower hemisphere.
|
||||
|
||||
_color
|
||||
_sunlight2_color
|
||||
.. skylight-key:: "light" "n"
|
||||
|
||||
_dirt
|
||||
_sunlight2_dirt
|
||||
Sets the dome light brightness. Equivalent to worldspawn key :worldspawn-key:`_sunlight2`.
|
||||
|
||||
_anglescale
|
||||
_anglescale
|
||||
.. skylight-key:: "_color" "r g b"
|
||||
|
||||
style
|
||||
flicker style for styled dome light
|
||||
Sets the dome light color. Equivalent to worldspawn key :worldspawn-key:`_sunlight2_color`.
|
||||
|
||||
targetname
|
||||
targetname for switchable sunlight
|
||||
.. skylight-key:: "_dirt" "n"
|
||||
|
||||
_suntexture
|
||||
this sunlight is only emitted from faces with this texture name
|
||||
Equivalent to worldspawn key :worldspawn-key:`_sunlight2_dirt`.
|
||||
|
||||
.. light-key:: "_sunlight3" "n"
|
||||
.. skylight-key:: "_anglescale" "n"
|
||||
|
||||
Same as :light-key:`_sunlight2`, but for the lower hemisphere.
|
||||
Equivalent to worldspawn key :worldspawn-key:`_anglescale`.
|
||||
|
||||
.. light-key:: "_nostaticlight" "n"
|
||||
.. skylight-key:: "style" "n"
|
||||
|
||||
Flicker style for styled sky light.
|
||||
|
||||
.. skylight-key:: "targetname" "name"
|
||||
|
||||
Targetname for switchable skylight.
|
||||
|
||||
.. skylight-key:: "_suntexture" "texname"
|
||||
|
||||
This sky light is only emitted from faces with this texture name. Default is to be emitted from all sky textures.
|
||||
|
||||
Set to 1 to make the light compiler ignore this entity (prevents it
|
||||
from casting any light). e.g. could be useful with rtlights.
|
||||
|
||||
Lighting Channels
|
||||
=================
|
||||
|
|
|
|||
|
|
@ -1,2 +1,3 @@
|
|||
sphinx==6.2.1
|
||||
furo==2023.3.27
|
||||
sphinx==7.2.6
|
||||
furo==2024.1.29
|
||||
sphinx-autobuild==2024.2.4
|
||||
|
|
|
|||
|
|
@ -4,58 +4,71 @@
|
|||
#
|
||||
# pip-compile requirements.in
|
||||
#
|
||||
alabaster==0.7.13
|
||||
alabaster==0.7.16
|
||||
# via sphinx
|
||||
babel==2.12.1
|
||||
babel==2.14.0
|
||||
# via sphinx
|
||||
beautifulsoup4==4.12.2
|
||||
beautifulsoup4==4.12.3
|
||||
# via furo
|
||||
certifi==2023.7.22
|
||||
certifi==2024.2.2
|
||||
# via requests
|
||||
charset-normalizer==3.1.0
|
||||
charset-normalizer==3.3.2
|
||||
# via requests
|
||||
docutils==0.19
|
||||
colorama==0.4.6
|
||||
# via
|
||||
# sphinx
|
||||
# sphinx-autobuild
|
||||
docutils==0.20.1
|
||||
# via sphinx
|
||||
furo==2023.3.27
|
||||
furo==2024.1.29
|
||||
# via -r requirements.in
|
||||
idna==3.4
|
||||
idna==3.6
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
jinja2==3.1.3
|
||||
# via sphinx
|
||||
markupsafe==2.1.2
|
||||
livereload==2.6.3
|
||||
# via sphinx-autobuild
|
||||
markupsafe==2.1.5
|
||||
# via jinja2
|
||||
packaging==23.1
|
||||
packaging==23.2
|
||||
# via sphinx
|
||||
pygments==2.15.1
|
||||
pygments==2.17.2
|
||||
# via
|
||||
# furo
|
||||
# sphinx
|
||||
requests==2.31.0
|
||||
# via sphinx
|
||||
six==1.16.0
|
||||
# via livereload
|
||||
snowballstemmer==2.2.0
|
||||
# via sphinx
|
||||
soupsieve==2.4.1
|
||||
soupsieve==2.5
|
||||
# via beautifulsoup4
|
||||
sphinx==6.2.1
|
||||
sphinx==7.2.6
|
||||
# via
|
||||
# -r requirements.in
|
||||
# furo
|
||||
# sphinx-autobuild
|
||||
# sphinx-basic-ng
|
||||
sphinx-basic-ng==1.0.0b1
|
||||
sphinx-autobuild==2024.2.4
|
||||
# via -r requirements.in
|
||||
sphinx-basic-ng==1.0.0b2
|
||||
# via furo
|
||||
sphinxcontrib-applehelp==1.0.4
|
||||
sphinxcontrib-applehelp==1.0.8
|
||||
# via sphinx
|
||||
sphinxcontrib-devhelp==1.0.2
|
||||
sphinxcontrib-devhelp==1.0.6
|
||||
# via sphinx
|
||||
sphinxcontrib-htmlhelp==2.0.1
|
||||
sphinxcontrib-htmlhelp==2.0.5
|
||||
# via sphinx
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
# via sphinx
|
||||
sphinxcontrib-qthelp==1.0.3
|
||||
sphinxcontrib-qthelp==1.0.7
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==1.1.5
|
||||
sphinxcontrib-serializinghtml==1.1.10
|
||||
# via sphinx
|
||||
urllib3==2.0.7
|
||||
tornado==6.4
|
||||
# via livereload
|
||||
urllib3==2.2.0
|
||||
# via requests
|
||||
|
|
|
|||
Loading…
Reference in New Issue