KeenEyes SDK

The KeenEyes SDK packages simplify project setup by providing sensible defaults, automatic package references, and custom item types for editor integration.

Quick Start

Replace the standard SDK with KeenEyes.Sdk:

<Project Sdk="KeenEyes.Sdk/0.1.0">
</Project>

That's it! Your project is now configured with:

• .NET 10 targeting
• C# 13 features enabled
• Nullable reference types
• AOT compatibility
• KeenEyes.Core and Generators referenced

SDK Packages

Package	Use Case	Output Type	Dependencies
KeenEyes.Sdk	Games and applications	Exe	Core + Generators
KeenEyes.Sdk.Plugin	Plugin libraries	Library	Abstractions + Generators
KeenEyes.Sdk.Library	Reusable ECS libraries	Library	Core + Generators

Game SDK

For standalone games and applications:

<Project Sdk="KeenEyes.Sdk/0.1.0">
  <!-- Everything configured automatically -->
</Project>

Plugin SDK

For plugins that extend KeenEyes without depending on Core:

<Project Sdk="KeenEyes.Sdk.Plugin/0.1.0">
  <!-- References Abstractions, not Core -->
</Project>

To include common components:

<Project Sdk="KeenEyes.Sdk.Plugin/0.1.0">
  <PropertyGroup>
    <IncludeKeenEyesCommon>true</IncludeKeenEyesCommon>
  </PropertyGroup>
</Project>

Library SDK

For creating reusable NuGet packages:

<Project Sdk="KeenEyes.Sdk.Library/0.1.0">
  <PropertyGroup>
    <PackageId>MyCompany.KeenEyes.Physics</PackageId>
    <Description>Custom physics components</Description>
  </PropertyGroup>
</Project>

The Library SDK enables IsPackable=true and GenerateDocumentationFile=true by default.

Default Properties

The SDK sets these defaults (all can be overridden):

Property	Default	Description
TargetFramework	net10.0	.NET version
LangVersion	preview	C# 13 features
Nullable	enable	Nullable reference types
ImplicitUsings	enable	Implicit global usings
IsAotCompatible	true	Native AOT ready
TreatWarningsAsErrors	true	Strict compilation
EnableNETAnalyzers	true	Code analysis

Overriding Defaults

Set properties explicitly to override:

<Project Sdk="KeenEyes.Sdk/0.1.0">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Automatic Package References

Opting Out

Disable automatic package references:

<PropertyGroup>
  <!-- Don't include KeenEyes.Core -->
  <IncludeKeenEyesCore>false</IncludeKeenEyesCore>

  <!-- Don't include KeenEyes.Generators -->
  <IncludeKeenEyesGenerators>false</IncludeKeenEyesGenerators>

  <!-- Don't include the KESL shader generator -->
  <IncludeKeenEyesShaders>false</IncludeKeenEyesShaders>

  <!-- Plugin SDK only: Include KeenEyes.Common -->
  <IncludeKeenEyesCommon>true</IncludeKeenEyesCommon>
</PropertyGroup>

The Game SDK includes KeenEyes.Core, KeenEyes.Generators, and KeenEyes.Shaders.Generator by default.

Adding Feature Packages

Add additional KeenEyes packages as needed:

<Project Sdk="KeenEyes.Sdk/0.1.0">
  <ItemGroup>
    <PackageReference Include="KeenEyes.Physics" Version="0.1.0" />
    <PackageReference Include="KeenEyes.Graphics.Silk" Version="0.1.0" />
  </ItemGroup>
</Project>

Custom Item Types

The SDK defines item types for game assets and editor integration.

A note on what these do at build time today: code generation for .kescene, .keprefab, and .keworld files is driven by AdditionalFiles — the SDK auto-detects files with those extensions and registers each one as both an AdditionalFiles entry (consumed by the source generators, which emit Spawn<Name> methods for scenes/prefabs and Configure<Name>/Apply<Name> methods for world configs) and the corresponding item type. The <KeenEyesScene>/<KeenEyesPrefab>/<KeenEyesWorld> items themselves only feed build-log messages and are bookkeeping for future editor integration. <KeenEyesAsset> is the one item type with build-time behavior of its own: matching files are copied to the output directory.

Scenes

Scene files define world configuration and entity setup:

<ItemGroup>
  <KeenEyesScene Include="Scenes/**/*.kescene" />
</ItemGroup>

Prefabs

Prefab files define reusable entity templates:

<ItemGroup>
  <KeenEyesPrefab Include="Prefabs/**/*.keprefab" />
</ItemGroup>

Assets

Game assets (textures, audio, data) are automatically copied to output:

<ItemGroup>
  <KeenEyesAsset Include="Assets/**/*" />
</ItemGroup>

World Configuration

World files define initial world setup:

<ItemGroup>
  <KeenEyesWorld Include="Worlds/**/*.keworld" />
</ItemGroup>

Shaders

Shader files written in KESL (KeenEyes Shader Language) are compiled at build time:

<ItemGroup>
  <KeenEyesShader Include="Shaders/**/*.kesl" />
</ItemGroup>

Shader Compilation (KESL)

When IncludeKeenEyesShaders is true (the default for the Game SDK), the SDK references KeenEyes.Shaders.Generator as an analyzer and auto-detects every **/*.kesl file in the project, registering it as both an AdditionalFiles entry and a <KeenEyesShader> item. The source generator compiles each shader to GLSL plus strongly-typed C# bindings during the build — no manual wiring or runtime shader parsing required. Set IncludeKeenEyesShaders=false to opt out (see Opting Out).

Asset Constants Generation

The SDK can generate type-safe, compile-time-validated constants for your asset paths so a typo in a texture or audio path becomes a build error rather than a runtime failure. It is off by default; enable it with GenerateAssetConstants:

<PropertyGroup>
  <GenerateAssetConstants>true</GenerateAssetConstants>
  <!-- Optional overrides (defaults shown) -->
  <AssetConstantsNamespace>$(RootNamespace)</AssetConstantsNamespace>
  <AssetConstantsClassName>Assets</AssetConstantsClassName>
  <AssetConstantsRootPath>$(MSBuildProjectDirectory)/Assets</AssetConstantsRootPath>
</PropertyGroup>

When enabled, asset files under AssetConstantsRootPath (images, audio, fonts, .json, .atlas, .keanim, .glb/.gltf, and more) are passed to the generator, which emits a static class (default name Assets) of path constants:

// Generated — usage
var texture = assetManager.Load<Texture>(Assets.Sprites.Player);

Version Information

The SDK exposes version metadata through MSBuild properties:

Property	Description
$(KeenEyesSdkVersion)	SDK package version
$(KeenEyesCoreVersion)	KeenEyes.Core version
$(KeenEyesMinimumCoreVersion)	Minimum compatible version
$(KeenEyesProjectType)	Game, Plugin, or Library
$(IsKeenEyesProject)	Always true for SDK projects

Generated Metadata

The SDK generates keeneyes.project.json in the output directory:

{
  "projectName": "MyGame",
  "projectType": "Game",
  "sdkVersion": "0.1.0",
  "coreVersion": "0.1.0",
  "targetFramework": "net10.0",
  "isAotCompatible": true
}

The file is emitted on every build so external tooling can detect and introspect KeenEyes projects. No tooling consumes it yet — the planned consumers (editor project detection, VS Code extension project discovery) are tracked in issue #386.

Comparison: SDK vs Manual Setup

With SDK

<Project Sdk="KeenEyes.Sdk/0.1.0">
</Project>

Without SDK (Manual)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>preview</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <IsAotCompatible>true</IsAotCompatible>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnableNETAnalyzers>true</EnableNETAnalyzers>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="KeenEyes.Core" Version="0.1.0" />
    <PackageReference Include="KeenEyes.Generators" Version="0.1.0"
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
  </ItemGroup>
</Project>

Troubleshooting

SDK Not Found

If you see "SDK not found" errors:

1. Ensure NuGet can resolve the SDK package
2. Check your nuget.config includes the KeenEyes package source
3. Try dotnet restore --force

Version Mismatch

The SDK version determines the Core/Generators versions. If you need specific versions:

<PropertyGroup>
  <IncludeKeenEyesCore>false</IncludeKeenEyesCore>
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="KeenEyes.Core" Version="0.2.0" />
</ItemGroup>

Disabling SDK Features

To use the SDK for conventions but manage dependencies manually:

<Project Sdk="KeenEyes.Sdk/0.1.0">
  <PropertyGroup>
    <IncludeKeenEyesCore>false</IncludeKeenEyesCore>
    <IncludeKeenEyesGenerators>false</IncludeKeenEyesGenerators>
  </PropertyGroup>

  <!-- Manual references -->
  <ItemGroup>
    <ProjectReference Include="../KeenEyes.Core/KeenEyes.Core.csproj" />
  </ItemGroup>
</Project>

See Also

• ADR-006: Custom MSBuild SDK - Design decision record
• Getting Started - New to KeenEyes?
• AOT Deployment - Native AOT compilation guide