LSCherry Framework
LSCherry makes creating NPR products for individuals and teams easy. It provides everything you need to integrate with Blender or Goo-Engine in a professional environment while supporting synchronization of third-party NPR libraries, offering flexibility to create various types of cel shading and stylized shading based on product needs. Starting from LSCherry Framework version 1.0.2, LSCherry requires Blender 4.0 or later.
LSCherry supports a variety of shading scenarios. Within a team, there are demands for synchronization and long-term stability across various models and environments built from multiple resources (e.g., merging multiple Blender files into a single Blender file). It also supports projects with frequent Blender or Goo-Engine version upgrades (e.g., from Blender 4.0.x to Blender 4.4.x). Some projects may apply multiple shading styles within the same environment, such as Toon, Handpainting, or Semi-real. Others might involve custom shading projects combined with LSCherry or rebuilding LSCherry with a different shading approach.
LSCherry is open source. It is a framework used in Lvoxx projects and consistently undergoes quality assurance over time.
The term "Cherry" has different meanings depending on the context. It can refer to the LSCherry Framework project, which is where it all began. Over time, other Cherry projects have been built on top of the LSCherry Framework. Most often, when people mention "Cherry," they are referring to the entire ecosystem of LSCherry projects. This reference documentation focuses on the foundation: the LSCherry Framework itself.
-
LSCherry
-
Cherry-BPotato
-
Cherry-OSL
-
Cherry-Comic
-
Cherry- ... and more
The LSCherry Framework is divided into multiple modules, and projects can select the modules that fit their needs. At the core of the framework are modules within the core container, including the configuration model and the SnapPuzzle mechanism. Additionally, the LSCherry Framework provides foundational support for various types of shading, including pattern, procedural material, composition, environment, and game built-in shading, as well as cel shading. It also includes LSCherry Core (Dot), a shading framework based on Phong (N dot L-vector), and, in parallel, LSCherry Game Built-In and Simple Procedural Material.
The initial version of LSCherry was created around July 2023, based on the custom toon shading framework of aVersionOfReality. It featured several custom ramp functions and basic toon shading capabilities aligned with the features available in Blender 3.0 and 3.1. During this period, LSCherry was able to fulfill the requirements for custom toon shading but still had several shortcomings in terms of user experience and functionality synchronization when combined with various types of toon shading. The final version supported during this phase was LSCherry 105.
By version LSCherry 1.0.0, all features were built with a focus on modular assembly and functional node distribution.
When exploring a framework, it is essential not only to know what it does but also to understand the principles it adheres to. Below are the core principles of the LSCherry Framework:
-
Provide choices at every level. LSCherry allows you to defer design decisions until they are truly necessary. For example, you can switch between core and dot functionality through Geometry nodes without altering shading logic.
-
Accommodate diverse perspectives. LSCherry embraces flexibility and does not impose a rigid approach. It supports a wide range of shading requirements with different perspectives.
-
Maintain strong backward compatibility. The development of LSCherry is carefully managed to minimize breaking changes between versions. LSCherry supports a carefully selected range of Blender versions and third-party libraries to help sustain applications and libraries dependent on it.
-
Focus on Shading Flow. The LSCherry team dedicates significant time and effort to creating intuitive and robust nodes that remain reliable across multiple versions and years.
-
Set high standards for node quality. The LSCherry Framework places a strong emphasis on providing meaningful, comprehensive, and accurate documentation. It is one of the few projects with a clean code structure, free from circular dependencies between packages.
For usage guidance or troubleshooting and debugging questions, we recommend using Blender StackExchange. Using LSCherry tag. If you are certain there is an issue in the LSCherry Framework or wish to propose a new feature, please use Github Issues.
If you already have a solution or a suggested fix, you can submit a pull request on GitHub. However, please note that for all but the simplest issues, we expect a ticket to be created in the issue tracker, where discussions can take place and leave a record for future reference.
If you are new to LSCherry, you might want to start using the LSCherry Framework by creating a shader based on LSCherry. LSCherry provides a quick (and guided) way to create a render-ready application based on LSCherry. It is built on the LSCherry Framework, prioritizing configuration-based workflows and designed to help you get started as quickly as possible.
You can use Make Toon to create a basic project or follow one of the "How to use this ?" guides, such as Getting Started Genshin Shading. These guides are easier to grasp, task-focused, and most of them are based on LSCherry. They also include other projects from the LSCherry ecosystem that you might consider when addressing a specific problem.
The core of LSCherry lies in Make Toon (Eevee) and Ray Toon (Cycles). All its main operations revolve around one of these nodes, except for nodes specifically designated for transparency, emission, or special cores. The main processing flow of LSCherry is single-threaded, accompanied by its associated configurations.
It starts with textures (either RGB or procedural). For special game shading, built-in packages will intervene, integrating with the Style Ramp and Global Config. Finally, it combines with post-production to create special effects without relying on core shading mechanics.
In the future, there will be an addon to support global configuration, making it easier to synchronize shading.
This is one of the key cores of LSCherry, equivalent to Blender's Principled BSDF when starting a material. You can adjust the sockets in this node to create basic shading as needed.
Base Color: The basic color (texture) of the object. The default is red.
Shadow Color(1): The shadow color, representing the darker part of the toon. The default is #750000 (similar to Crimson).
Note: This color is independent of the environment. When World Color is enabled, the color will be blended according to the mechanism. The default final color is calculated as:
Final Color = Combine((R-base + R-blend) / 2, (G-base + G-blend) / 2, (B-base + B-blend) / 2).
SSS Color(2): The transition color between the light ramp and the dark ramp, similar to Subsurface Scattering. The default is #E06600 (similar to Orange).
Rim Color(2): The color separating the object from the environment. The default is white.
Back Color(2): This section can only be used in combination with the geometry modifier Core.LSCherryProvider. It allows controlling Rim Light based on a vector, which can be either the Sun or an Axis object.
Rim Strength: Controls the intensity of the rim light effect.
- Range: 0.000 to 1.000
- Default: 0.100
Rim Size: Adjusts the size of the rim light effect on the object.
- Range: 0.000 to 1.000
- Default: 0.300
Roughness: Sets the roughness value for the rim light, influencing its softness.
- Range: 0.000 to 1.000
- Default: 0.000
Pattern: Applies patterns to the Diffuse, with the default color set to white. The intensity of the effect depends on the input value; the smaller the value, the stronger the effect. This socket is useful for hand-drawn shading styles such as cross-hatching, hatching, stippling, contour hatching, scribbling, and more.
- Range: Black to White
- Default: White
Emission: Sets the color of the emission effect. If black, the emission is disabled. Learn more:
Emission Strength: Determines the brightness of the emission.
- Range: 0.000 to ∞
- Default: 1.000
Alpha: Controls the transparency of the material.
- Range: 0.000 (fully transparent) to 1.000 (fully opaque)
- Default: 1.000
Default Normal: Configures the default normal mapping. Use it for additional normal map blending.
- Range: 0.000 to 1.000
- Default: 1.000
Normal This section allows detailed control of normal mapping. Additional options may appear based on connected nodes.
- Default: bluey-purple colours or #8080FF
Learn more:
Ramp Style allows adjusting the shading of the ramp using three nodes: Toon Style, SSS Style, and Back Style. The inputs of the nodes are marked as normal but are not actually normal because Blender currently does not allow input sockets to be of a Map type. It is recommended to manually input a value into the socket instead of dragging and connecting it to avoid rendering errors in Blender.
To override a Style later, connect a corresponding Style node in front of it.
Toon Style
SSS Style
Back Style
- To temporarily disable this socket, set the color to white.
- To temporarily disable this socket, set the color to black.