Project Generation

Understanding how S2D CLI generates projects, build configurations, and templates.

🔗 Overview

S2D CLI creates complete, ready-to-run game projects with minimal configuration. The generation process involves:

1. User input collection (project name, build system, location)
2. Project directory creation
3. Library dependencies download from GitHub
4. Build system configuration
5. Template code generation
6. Platform-specific setup

🔗 Build Systems

S2D CLI supports two build systems with different approaches and target audiences.

Scala-CLI (Recommended)

The default and recommended option for new users and rapid prototyping.

Advantages

• Simpler configuration with directive comments
• Faster startup for small projects
• Single file configuration
• Great for learning and experimentation

Generated Files

• project.scala - Build configuration with native linking directives
• main.scala - Application template

Example project.scala

//> using scala 3.3.6
//> using platform native
//> using dep "io.github.finochiom:s2d_native0.5_3:0.1.6"

//> using nativeCompile "-IC:\\path\\libraries\\SDL2\\include"
//> using nativeCompile "-IC:\\path\\libraries\\STB\\include"
//> using nativeCompile "-IC:\\path\\libraries\\glew\\include"

//> using nativeLinking "-LC:\\path\\libraries\\SDL2\\lib"
//> using nativeLinking "-lSDL2" "-lSDL2main" "-lglew32"

SBT

Traditional Scala build tool for more complex projects and teams.

Advantages

• Industry standard for Scala projects
• Better for larger, multi-module projects
• Rich plugin ecosystem
• Advanced dependency management

Generated Files

• build.sbt - Main build configuration
• project/plugins.sbt - Scala Native plugin
• project/build.properties - SBT version
• main.scala - Application template

Example build.sbt

ThisBuild / version := "0.1.0-SNAPSHOT"
ThisBuild / scalaVersion := "3.3.6"

lazy val root = (project in file("."))
  .settings(
    name := "s2d-project",
    libraryDependencies ++= Seq(
      "io.github.finochiom" % "s2d_native0.5_3" % "0.1.6"
    ),
    nativeConfig ~= { c =>
      c.withLinkingOptions(c.linkingOptions ++ Seq(
        "-LC:\\path\\libraries\\SDL2\\lib",
        "-lSDL2", "-lSDL2main", "-lglew32"
      ))
    }
  )
  .enablePlugins(ScalaNativePlugin)

🔗 Project Structure

Generated projects follow a consistent structure regardless of build system:

my-s2d-project/
├── main.scala                  # Entry point and game template
├── assets/                     # Asset directory for sprites, sounds, etc.
├── libraries/                  # Downloaded S2D dependencies
│   ├── SDL2/                   # SDL2 library files
│   │   ├── include/            # Header files
│   │   ├── lib/                # Static libraries (Windows)
│   │   └── bin/                # DLLs (Windows)
│   ├── glew/                   # GLEW library files
│   │   ├── include/
│   │   └── lib/
│   └── STB/                    # STB image library
│       └── include/
├── project.scala               # Scala-CLI config (if chosen)
├── build.sbt                   # SBT config (if chosen)
├── project/                    # SBT project files (if chosen)
│   ├── plugins.sbt
│   └── build.properties
├── SDL2.dll                    # Runtime DLL (Windows only)
└── glew32.dll                  # Runtime DLL (Windows only)

Directory Purposes

• assets/ - Store game assets (images, sounds, maps)
• libraries/ - Native dependencies automatically downloaded
• project/ - SBT build system files
• *.dll - Runtime libraries for Windows execution

🔗 Template Files

S2D CLI generates a working game template that demonstrates basic S2D usage.

Generated main.scala

import s2d.core.{Window, Drawing}
import s2d.types.*

object main {
  def main(args: Array[String]): Unit = {
    println("S2D Project Template")
    println("Starting S2D application...")
    
    // S2D library (version 0.1.6) is automatically imported
    // Create a window using S2D
    Window.create(800, 600, "My S2D Application")
    
    // Main game loop
    while !Window.shouldCloseWindow() do
      Drawing.beginFrame()
      Drawing.clear(Color.fromHex("#3498DB").getOrElse(Color.Blue))

      // TODO: Add your game logic here

      Drawing.endFrame()
    Window.close()
    println("S2D application terminated.")
  }
}

Template Features

• Window Creation - 800x600 window with custom title
• Game Loop - Standard begin/end frame pattern
• Background Color - Blue background (#3498DB)
• Proper Cleanup - Window close handling
• Console Output - Status messages for debugging

Running the Template

The generated template creates a working S2D application:

# For Scala-CLI projects
scala-cli run .

# For SBT projects
sbt run

🔗 Library Setup

S2D CLI automatically handles library dependencies and native library setup.

S2D Library Versioning

The CLI automatically fetches the latest S2D version from GitHub releases:

• Queries GitHub API for latest tag
• Uses format: io.github.finochiom:s2d_native0.5_3:VERSION
• Falls back to version 0.1.6 if API fails

Native Libraries Download

Required native libraries are cloned from the S2D_Libraries repository:

git clone https://github.com/FinochioM/S2D_Libraries.git libraries/

Platform-Specific Configuration

Windows (Automatic)

• Full library paths configured in build files
• DLLs copied to project root for runtime
• Include directories set up for compilation

Unix/Linux/macOS (Manual)

• Build configuration commented out
• Warning messages displayed
• User must install system libraries and uncomment configuration

🔗 Customization

Once generated, you can customize your S2D project in several ways.

Project Configuration

Changing S2D Version

Update the dependency version in your build file:

// Scala-CLI
//> using dep "io.github.finochiom:s2d_native0.5_3:NEW_VERSION"

// SBT
libraryDependencies ++= Seq(
  "io.github.finochiom" % "s2d_native0.5_3" % "NEW_VERSION"
)

Adding Dependencies

Add additional Scala libraries as needed:

// Additional JSON library example
//> using dep "com.lihaoyi::upickle:3.1.0"

Code Structure

Organizing Game Code

Expand beyond the template with proper structure:

src/
├── main/
│   └── scala/
│       ├── Main.scala          # Entry point
│       ├── GameState.scala     # Game state management
│       ├── entities/           # Game entities
│       ├── systems/            # Game systems
│       └── assets/             # Asset loading

Adding Game Logic

Replace the TODO comment with your game implementation:

// Replace the TODO section with:
player.update(deltaTime)
enemies.foreach(_.update(deltaTime))
handleCollisions()
renderEntities()

Asset Management

Use the generated assets/ directory for game resources:

assets/
├── sprites/
│   ├── player.png
│   └── enemies/
├── sounds/
│   └── music/
└── maps/
    └── level1.json