Projects¶

Understanding Projects in Lemonate¶

In Lemonate, every game project has a specific structure that deserves a bit of explanation. Think of it like unpacking a gift: there’s more to it than meets the eye.

When you create your first game project and open it in the editor, you’ll notice a few items and folders already waiting for you in the Project view. Don’t worry, some other folders will magically appear later as needed. But before we dive into the details, let’s talk about the term “Item.”

Why “Item” and not “File”? Well, that’s not just Lemonate trying to be quirky. There’s an important distinction here. While items might look like files, they’re not. An item in Lemonate is a database entry that includes metadata, attributes, and links. Some items may also include a file payload and even attachments. Confused? Let’s break it down:

Anatomy of an Item¶

• Attributes: At their simplest, attributes are key-value pairs. For example, a material item might include attributes like “Diffuse Color,” “Emissive Color,” or “Opacity.” But it doesn’t stop there! Some items have more complex attributes. A scene item, for instance, contains a scenegraph (a tree structure that holds your game’s hierarchy).

• Links: Items often link to other items. For example, a project links to one or more scenes, scenes link to models, models link to materials, and so on. See graph below to see what items can link to what other items.

• File Payloads: These are the actual files associated with items, like the image data for textures or the mesh data for 3D models.

• Attachments: Attachments are additional binaries, often generated by the engine. For example, textures may include different levels of detail (mipmaps), and many items have preview images attached. These previews allow you to see what items look like without downloading or rendering them fully—convenient, right?

Links between items¶

The following graph shows how items can be linked:

        graph TD
    Project["Project (Main)"]
    VariableSet["Variable set"]
    Scene["Scene"]
    Mesh["Mesh"]
    Material["Material"]
    Image["Image"]
    Script["Script"]
    PixelShader["Pixel Shader"]
    VertexShader["Vertex Shader"]
    BackgroundShader["Background Shader"]
    Composition["Composition"]
    Font["Font"]
    ParticleSystem["Particle System"]

    Project --> Scene
    Project --> VariableSet
    Scene --> BackgroundShader
    Scene --> Composition
    Scene --> Script
    Scene --> Mesh
    Scene --> Material
    Scene --> Image
    Scene --> Font
    Scene --> ParticleSystem
    Mesh --> Material
    Material --> Image
    Material --> PixelShader
    Material --> VertexShader
    Material --> Composition
    ParticleSystem --> Image
    

The Project Root¶

At the root of your project, you’ll find the “Main” item, which is of type Project. This is essentially your entire game in one neat package. Everything else—scenes, assets, scripts—branches out from here.

You’ll also find a resources folder with subfolders like compositions and scripts. These are where you can store the assets you create or upload. Of course, you’re free to organize your folders however you like, but following Lemonate’s suggested structure makes it easier for others to navigate your project (especially if they remix it).

Packages: The Asset Burritos¶

One folder you won’t see right away is packages. It’ll appear when needed. This folder stores any asset packages you use from the asset store once you copy them to your project. Usually you will not copy assets from the store to your project right away since it is easier to just reference them during development and only copy them to your project, once you are sure you want to keep them.

Packages are essentially zip files that bundle all the items related to an asset. If you want to modify an asset, you can unpack the package, but keeping it packed is generally recommended. Why? Because loading one big package is faster than loading a ton of tiny items from the cloud. Speed is king in the digital realm!

Publishing: The Final Countdown¶

Another folder that makes a dramatic entrance when required is published. This folder holds all the packaged and published versions of your project. Inside published, you’ll find subfolders named after your project’s version numbers (e.g., 1.0.0). These contain the actual package that others will play or use.

Here’s the crucial part: the `published` folder is the magic box where your game lives for the outside world. If you delete a package from here, it’s gone—poof!—from the asset store or games page. No secret backup servers or hidden vaults. If it’s not in published, it’s not in Lemonate.

So treat this folder like a treasure chest. Guard it well, and always know what’s inside.

—

That’s the gist of projects in Lemonate! Dive in, explore, and remember: your project’s structure is the foundation of your game. Keep it organized, and the fun will follow.