\section{Getting Started}
\label{sec:getting-started}

\subsection{Requirements}

The package is meant for LuaLaTeX. A typical document loads TikZ and then loads
\verb|lua-tikz3dtools| in the preamble. The runtime depends on the Lua module
files as well as the style file, so both the TeX loader and the Lua module
loader must be able to find the package installation.

For normal use, install the package into a TeX tree. For local development from
the repository checkout, ensure that the \verb|src/| directory is visible on both
the TeX input path and the Lua input path before compiling the manual examples.

\subsection{A minimal document}

The following example shows the smallest complete workflow that still exercises
the package properly: a light, a triangle, a label, and a final display call.

\begin{Verbatim}
\documentclass{article}
\usepackage{lua-tikz3dtools}

\begin{document}
\begin{tikzpicture}
  \appendlight[
    v = {return Vector:new{0, 0, 1, 1}}
  ]

  \appendtriangle[
    m = {
      return Matrix:new{
        {0, 0, 0, 1},
        {2, 0, 0, 1},
        {0.5, 1.25, 1.0, 1}
      }
    },
    fill options = {fill=ltdtbrightness, draw=black}
  ]

  \appendlabel[
    v = {return Vector:new{0.8, 0.35, 0.35, 1}},
    text = {$T$}
  ]

  \displaysimplices
\end{tikzpicture}
\end{document}
\end{Verbatim}

There are three practical points hidden in this minimal example.

First, every geometric command appends data to the scene; nothing is drawn until
\verb|\displaysimplices| is executed. Second, lighting only affects the rendered
triangle if the triangle's fill style actually refers to the dynamically defined
color \verb|ltdtbrightness|. Third, the coordinates are three-dimensional even
though the final output is a two-dimensional TikZ path.

\input{figures/02-getting-started-scene.tex}

\subsection{The basic workflow}

Most figures built with lua-tikz3dtools follow the same order:

\begin{enumerate}[leftmargin=2em]
\item open a \verb|tikzpicture|;
\item optionally define reusable Lua values with \verb|\setobject|;
\item append geometry and labels in any convenient order;
\item optionally append lights;
\item call \verb|\displaysimplices| exactly where the scene should be emitted.
\end{enumerate}

The append order is not the final render order. The package recomputes that order
from geometry. This is the main distinction between lua-tikz3dtools and the
manual ``draw the farthest object first'' approach.

\subsection{A slightly richer first scene}

The next example shows two useful habits from the start: keep the transformation
separate from the geometric definition, and use \verb|\setobject| when the same
value appears more than once.

\begin{Verbatim}
\begin{tikzpicture}
  \setobject[
    name = tilt,
    object = {
      return Matrix.axis_angle(Vector:new{1, 0, 0, 1}, 0.9)
        :multiply(Matrix.axis_angle(Vector:new{0, 0, 1, 1}, 0.7))
    }
  ]

  \appendlight[
    v = {return Vector:new{0.4, -0.3, 1, 1}}
  ]

  \appendtriangle[
    m = {
      return Matrix:new{
        {-1, -1, 0, 1},
        { 1, -1, 0, 1},
        { 0,  1, 0, 1}
      }
    },
    transformation = {return tilt},
    fill options = {fill=ltdtbrightness, draw=black}
  ]

  \appendlabel[
    v = {return Vector:new{0, 0.2, 0.1, 1}},
    transformation = {return tilt},
    text = {$\Sigma$}
  ]

  \displaysimplices
\end{tikzpicture}
\end{Verbatim}

This scene is already structured the same way as larger ones: a few named values,
local command keys, and a single display call. Once that pattern is comfortable,
the rest of the manual is mostly about richer sources of geometry.