snowflakepowered/snowflake

:snowflake: :video_game: Emulator Frontend and SDK

Build Status

Windows	Linux

Latest Version

Snowflake is a framework for building flexible and beautiful emulator frontends. With features such as advanced configuration generation and an intelligent scraping system, Snowflake provides a powerful set of tools to manage, play, and organize your games when designing your dream frontend using the language of your choice.

Features

Snowflake features innovative solutions to many problems with current emulator frontends.

• Full cross-patform support through .NET Core.
• Dynamic and flexible tree-based game scraping.
• Programmatic per-game emulator configuration generation and input management.
• Multi-disc and multi-file capable relational games database.

At its core, Snowflake is designed to be moddable and easy to develop for, with a comprehensive C# API for extensibility and GraphQL interface for frontend UIs.

• Language-agnostic GraphQL interface for communicating with the Snowflake framework.
• Plugin API to extend the framework with C# plugins.
• Module-based runtime extensibility.
• Stone platform, controller, and canonical ROM file mimetype compliant.
• Dedicated CLI to help you get started quickly and easily.

Star this repository and bookmark our website at http://snowflakepowe.red to keep up with Snowflake's development. We'll have something new in store for you soon!

Getting Started

Snowflake does not currently have a well defined install process for end-users, but it is easy to set up a development environment. You will need the .NET 6 SDK to get started.

$ git clone --recursive https://github.com/SnowflakePowered/snowflake/
$ cd snowflake
$ dotnet run --project build -- Bootstrap
$ cd out
$ dotnet snowflake install-all

This command will build and install all support modules required for Snowflake to be functional to your application data directory (%appdata%\snowflake\modules or ~/.snowflake/snowflake/modules on Linux). Note that you may have to delete the installed module assembly.Snowflake.Framework.Test.InvalidComposable, which is designed deliberately to error on load, however this is not necessary.

As well, input management APIs are currently only available on Windows. Attempting to use these APIs on Linux will fail to enumerate any device.

Legal

Snowflake is licensed under the Mozilla Public License 2.0 (MPL2). Since May 1, 2016, this license is retroactively applied to all prior copies of Snowflake's source code which may have been licensed under different terms.

Snowflake does not in any way facilitate the download of illegal ROM images or warez of any kind.

snowflake's Issues

Implement a WebSockets transport for Javascript API

Non-nodejs backed javascript API

We need a vanilla/jQuery based javascript API for Snowflake core ajax, as part of atom-shell migration

CMPDats identifier truncates numbers

Increase test code coverage

• 10% Code coverage
• 20% Code coverage
• 30% Code coverage
• 40% Code coverage
• 50% Code coverage
• 60% Code coverage
• 70% Code coverage
• 80% Code coverage

Create NuGet package

Create a NuGet library package for Snowflake.API and Snowflake

Create a per-emulator bridge database to store Configuration flags

MediaStore; Decouple from Platforms

Make mediastore exclusive to games

Split off and remove plugins into separate projects

snowflake.sln should only contain the API, the Implementation, and the Bootstrap

Add enhanced logging functionality

Log when

• A platform is loaded
• A controller is loaded
• A plugin is loaded
• Core completes loading
• An AJAX call is made
• An AJAX call returns
• Game information has been accessed
• A Game is added to the game database
• A Game is removed from the game database
• A set of GameInfoResults are scraped
• A Game is scraped from a GameInfoResult

Fix json parsing of platforms

Currently we can't parse PlatformInfos due to interface changes

Remove SharpYaml dependency

Migrate all uses of yaml to json to remove the dependency on SharpYaml. I believe the only thing that still uses SharpYaml is EmulatorAssembly def files.

StandardAjax: Mark Required parameters

Since PR #76, Ajax methods have the capability to mark parameters as required, wherein the AjaxManager will fail the request if the parameter is not present. However, in Snowflake.StandardAjax no method has yet to have parameters marked as required.

Create view selector

Linux/Mono support

While it would be best if snowflake was ported to .NET Core rather than running on top of Mono, .NET Core is far from production ready and is missing a large part of the BCL that Snowflake and dependencies use. For the time being, ensure that Snowflake.API and Snowflake.Core are able to be run under Mono.

Merge IConfigurationStore and IConfigurationFlagDatabase

There's no reason IConfigurationFlagDatabase entries can't be stored as a json entry. It'd be better if methods like GetFlags() and GetConfig() could be accessible through the same class instead of having to init a new database.

What needs to happen before API is feature-complete

Emulator API

• A way to store and load custom game profiles during configuration compilation (ConfigurationStore)
• A way to store and load configured controller profiles (filesystem?)
• A way to store and load emulator-specific flags for certain games (use a database)
• Implementing common logic in the abstract base class

Others

• A massive refactoring is required, sorting every class into a distinct API
• Documenting interfaces for every core class
• Completely remove the SharpYaml dependency, just migrate everything to json.net.
• EventManager API should be implemented AFTER refactoring
• Unit and integration tests if possible

Scraper: Separate getting scraper results from information

Currently, the scraper service works by first getting the scraper results, then the information using the best result. We want to separate this so that plugins and Ajax have a chance to intercept this information, which then we will call the "information" getting part, which will return the GameInfo. This is expected to add one method to the IScraperService interface

Predicted Breakages
- IScraperService

Add a store to keep ConfigurationProfiles

Simply a folder will do, have the profile name be identical to the filename of the ROM to have it apply rather than having a dedicated setting perhaps?

Replace flags.db with JSON-backed Configuration Flag Store

SQLite is a poor fit for the unstructured, unschema'd format of flexible configuration flags. That should be migrated to a JSON document store that emulator bridge plugins can access lazily and easily.

[Emulator-SnowflakeRetroarch] Implement proper Joystick Index setting

If the configured controller is a joystick, set JOYPAD_INDEX properly so retroarch picks up on the correct joystick. Remember to disable controller auto-config as well.

CoreService: Abstract away servers in a collection

Currently servers are part of the CoreService interface. Because all the servers share a common StartServer and StopServer method, this can be easily abstracted away into a specialized collection object so that plugins have access to the server framework, and that new servers do not break CoreService.

Store ROM CRC32 in GameInfo

Allows for quick and easy identification of a certain game.

Use JSON for internal structures such as ConfigurationTemplates

JSON is used in internal structures such as plugin.json or platform definition files. JSON is already used for such structures, so ControllerTemplates, ConfigurationTemplates and InputTemplates should also be written in JSON for consistency.

ConfigurationProfiles will remain in YAML, however ControllerProfiles should be written in JSON, as they are meant to be machine-generated. Should YAML prove difficult to write ConfigurationProfiles in, they will be done in JSON as well.

Make configuration flags values a thin wrapper over IDictionary<string, dynamic>

Instead of hardcoding what types of metadata make up a certain type of flag, just throw all the metadata inside a dynamic dictionary instead. This removes the need for unescessary parsing and there is no need to enforce a standard by way of code, instead simply refuse to comply with non standard flag definitions.

Implement an Events API

The Events API should be the driver behind Snowflake's Ajax Call -> Action Performed -> Return Ajax Result workflow

Migrate to atom-shell

Migrate all databases to use EntityFramework

Snowflake has 3 databases that derive from BaseDatabase, a thin wrapper around the SQLite Database Connection.

GamesDatabase, PlatformPreferencesDatabase and ControllerPortsDatabase can all be migrated to using EntityFramework ORM instead of running raw SQL.

Add Min/Max to int configuration flags

Add a minimum or maximum value to integer configuration flag values.

Improve MediaStoreServer Syntax

Port entire C# codebase to .NET Core

Move from .NET Framework 4.5 to .NET Core when it's production ready to ensure the API is cross-platform. At the moment neither the platform nor implementation use Windows-specific code, so this should be trivial. The only issue is that IEmulatorBridge plugins may not be able to be platform agnostic due the nature of wrapping an emulator assembly.

Tests: Use a mocking framework

Probably will switch tests to use Moq.

[Emulator-SnowflakeRetroarch] Properly handle issues where there are no joysticks plugged in

If there are no joysticks plugged in the plugin should automatically force Keyboard.

Hook up events

These events have been hooked.

CoreEvents should be hooked to the StandardAjax assembly. Events should be be tied too tightly to the core.

• GamePreAddEvent
• GameAddEvent
• AjaxRequestReceivedEvent
• AjaxResponseSendingEvent
• ServerStartEvent
• ServerStopEvent

Scraper: Port the-games-db to new scraper API

Since #63, the scraper API has changed and new responsibilities are required on part of the scraper plugin. The the-games-db scraper has to be updated to this new interface.

[Emulator-SnowflakeRetroarch] Implement fullscreen flag toggle

Improve PlatformDefaults and PlatformDefaultsDatabase

Currently, the ScrapeService runs all identifiers registered for a platform and as such no need is required for the PlatformDefaults Identifier column.

• Remove Identifier property from platform defaults

Platform Defaults are currently hard-set from .platform files on first run whether or not the plugins exist. The default plugins should be inferred from the loaded, available plugins for a platform. If no plugin exists to handle such a task, set the plugin to null.

• Remove defaults specification from .platform files
• Infer default plugins from available plugins

Currently, the interop method used to run a game requires a parameter specifying the emulator name. Usually this is read from and set to the PlatformDefaultsDatabase. Scrapers however are read from the Platform Defaults. This behaviour should be brought in line, the client frontend should have ultimate control over which scraper plugin is used.

• Allow ScrapeService to specify which scraping plugin is used rather than getting from the platform defaults
• Expose scrape plugin specifying in Javascript

StandardAjax: Implement Controller methods

The StandardAjax controller methods are mostly unimplemented

Emulator settings API

Build a basic Ajax API to begin frontend work

Game

• Game.GetGameResults(string fileName)
• Game.GetGameInfo(string fileName, object gameResult)
• Game.AddGameInfo(object gameInfo)
• Game.GetGame(uuid Game)
• Game.GetGamesForPlatform(string platform)
• Game.GetFlags(string emulator, uuid Game)
• Game.SetFlag(string emulator, string flag, string value, uuid Game)
• Game.StartGame(string emulator, uuid Game)
• Game.HaltRunningGames()
• Game.SearchGamesInPlatform(string query, string platform)
• Game.SearchGames(string query)

Platform

• Platform.GetPreferences(string platform)
• Platform.SetPreference(string platform)
• Platform.SetInputDevice(string controllerId, int slot)
• Platform.GetPlatforms()

Controller

• Controller.GetProfiles(string controllerId)
• Controller.SetInput(string controllerid, int slot, string button, string value)
• Controller.LoadProfile(string filename)

System

• System.GetEmulatorBridges()
• System.GetEmulatorBridgesForPlatform()
• System.GetScrapers()
• System.GetScrapersForPlatform()
• System.GetAllPlugins()
• System.GetAllAjaxMethods()
• System.SendEmulatorPrompt()
• System.ShutdownCore()
• System.GetCoreVersionString()

Document APIs

• Ajax API
• Controller API
• Emulator API
• Emulator Configuration API
• Emulator Input API
• Game API
• Identifier API
• Information API
• Platform API
• Plugin API
• Scraper API
• Service API
• Service Manager API
• Service HttpServer API

Parameterized Identifiers

Instead of passing a single string to the scraper, pass a dictionary of identifier-produced metadata with the identifier name as the key to the scraper. Identifiers will still return a single string, however the IScrapeService run all the identifiers that are registered for a platform and will add the result to a dictionary with the identifier plugin's name. Scrapers will receive this information, and will be able to access more information than just the name of a game, such as complete NFO strings for an NFO scraper, the filename, MD5, SHA1 and CRC32 hashes, and disc IDs for disc-based systems.

Predicted breakages

• IScraper API

Delete /theme folder

The /theme folder should be removed as the code therein is no longer compatible with the StandardAjax API and is obsolete; all theme development is done in theme-paper-snowflake.

Write atom shell bootstrap

Separate plugins

Create a database to store Controller profiles

Remove unnecessary usages of dynamic

I kinda went heavy-handed with the dynamic keyword but it's causing an unnecessary, albeit slight performance impact during startup when the profiles and plugins are loaded. In all places where it can be replaced with object without having to change the existing code, it should be, so the CLR doesn't look up the DLR every time it's used when it doesn't have to be.

node+server launcher

Create view for platforms

Make serializable objects have a JsonConverter

New Controller API

The current controller API is ambiguous and confusing to use. It is in desperate need of re-engineering, especially before release. As such, the following changes to the Controller API will be made.

• Controller Definitions will be split off from Platform definitions and be loaded separately into a dictionary.
• Platform controller ports, that is, which controller is plugged into which virtual port on the platform will be baked into the platform definition and will only be changeable through editing the platform definition.
• Controller mappings will be based on a per-input-device basis. Mappings will be supplied for keyboard and most popular controllers with the install as a single file. The file will contain multiple controller definition mappings that will map to Snowflake's gamepad or keyboard abstraction. It will be identified by the device name.
• Snowflake will store the input device identifier for each port on a platform. It is still dependent on the emulator bridge plugin to identify the name of the device and to provide adequate bindings.
• On Windows, XInput controllers will have their device name stored as Xinput1 through Xinput4. As such emulator plugins will be certain this is an Xinput device.
• Multitaps will continue to be unsupported.