KKoishi STG Engine

这款STG引擎为一个轻量的STG引擎，其使用Java2D和Java2D自带的OpenGL硬件加速进行渲染。它可以让你较轻松的实现一个stg的基本功能。

This STG engine is a lightweight STG engine, which uses Java2D and the hardware acceleration implemented by OpenGL in Java2D for rendering, and it allows you to implement the basic functions of a STG easily.

开启硬件加速的JVM参数:

JVM parameters for enabling hardware acceleration:

// https://docs.oracle.com/javase/8/docs/technotes/guides/2d/flags.html
-Dsun.java2d.ddscale=true
-Dsun.java2d.opengl=true
-Dswing.aatext=true
-Dawt.nativeDoubleBuffering=true

或者在main方法最开始调用Bootstrapper::enableHardwareAccelerationProperties方法。

Or call the Bootstrapper::enableHardwareAccelerationProperties method at the beginning of the main method.

⚠ 注意事项

本项目仅为个人兴趣而制作，开发目的在于学习和探索，一切开发皆在学习，请勿用于非法用途。因使用本项目产生的一切问题与后果由使用者自行承担，项目开发者不承担任何责任。

测试用例的素材仅为提供效果参考。

This project is only made for personal interest. The purpose of development is to learn and explore. All development is for learning. Please do not use it for illegal purposes. All problems and consequences arising from the use of this project shall be borne by the user, and the project developer shall not bear any responsibility.

The material of the test case is only for reference.

🕑 启动方法

本引擎提供了一个类top.kkoishi.stg.boot.Bootstrapper来快速启动，只需要调用方法去设置里面的各项参数即可。

This engine provides a class top.kkoishi.stg.boot.Bootstrapper to start quickly, so you can just call the method to set the various parameters inside.

请保证您具有一定的jvm语言基础。
在编译c++实现的启动程序前，请修改jar包路径等部分代码为您需要的内容。
下面的仅为说明示例，具体实现请参考top.kkoishi.stg.test.Test
正常构建jar包后(直接放class文件也行，你随意:D)，可以自己实现一套启动流程/启动脚本，也可以修改并编译在cpp_bootstrapper目录中提供的启动程序。
Please ensure that you have a certain jvm language foundation.
Before compiling the startup program implemented by c++, please modify some codes such as the jar path to the content you need.
The following codes is just an example, please refer to the detailed implementationtop.kkoishi.stg.test.Test
After building and packaging the jar file normally (you can directly use the class files:D), you can implement the startup processes or startup scripts, or just simply modify and compile the startup program provided in the cpp_bootstrapper directory.

//kotlin
Bootstrapper.readEngineSettings()
Bootstrapper().size(WIDTH, HEIGHT).autoSync().containerTitle("KKoishi_ Stg Engine Test")
    .fullscreen(fullScreen).scale(scale).useEngineDefaultIcon().useVRAM(useVRAM).uiInsets(
        UI_INSETS.top, UI_INSETS.left, UI_INSETS.bottom, UI_INSETS.right
    ).append(GFXLoader("${Threads.workdir()}/test/gfx"))
    .append(AudioLoader("${Threads.workdir()}/test/audio")).initMethod {
        // input your init method.
        // this method will be invoked after the container is built.
    }.start()

💫 Bootstrapper中的各项参数说明

参数	功能	修改方法	备注
height	设置窗口的高度 Set the height of the window	size	需要同时提供高度和宽度 Need to provide both height and width
weight	设置窗口的宽度 Set the width of the window	size	需要同时提供高度和宽度 Need to provide both height and width
useVRAM	是否使用GPU显存进行双缓冲 Whether to use GPU memory for double buffering	useVRAM	传入一个bool，决定屏幕缓冲内容是否使用VRAM储存 Pass in a bool to determine whether the screen buffer content should be stored in VRAM.
icon	设置窗口的图标 Set window icon	icon	传入图标图像文件所在的位置。可以使用useEngineDefaultIcon替代，这将会把图标换成引擎的默认图标 Pass in the location of the icon image file. You can use use Engine Default Icon instead, which will change the icon to the engine's default icon
autoSync	在窗口重新获得焦点后，是否同步逻辑帧率与渲染帧率 Whether to synchronize the logical frame rate and rendering frame rate after the window regains focus	autoSync	传入一个bool，开启后可以避免在失去焦点后在显示帧率时有误 Pass in a bool. When turned on, it can avoid errors in displaying the frame rate after losing focus.
scale	设置窗口放大到的大小 Set the size to which the window is enlarged	scale	传入放大后的窗口宽度和高度，此选项在全屏模式开启后会被屏蔽 Pass in the enlarged window width and height, this option will be blocked after the full screen mode is enabled
fullscreen	开启全屏模式 Enable full screen mode	fullscreen	传入一个bool，决定是否开启全屏。全屏可能会提高渲染效率也可能不会，取决于平台是否支持full-screen exclusive mode Pass in a bool to decide whether to enable full screen. Full screen may or may not improve rendering efficiency, depending on whether the platform supports full-screen exclusive mode
initMethod	窗口完成初始化后执行的方法 Method executed after the window completes initialization	initMethod	传入lambda表达式或者方法引用 Pass in lambda expression or method reference
title	设置窗口的标题 Set window title	title	传入字符串 Pass in a string
container	设置窗口 Set the window	container	传入JFrame或者其子类的实例。不建议修改，默认使用的是引擎自带的OptimizedContainer Pass in an instance of JFrame or its subclass, which is not recommended to modify it. What the engine uses by default is the OptimizedContainer.
uiInsets	设置侧边栏的间隔Insets Set the interval Insets of the sidebar	uiInsets	设置侧边栏的Insets。侧边栏就你打stg时旁边显示分数的玩意，这东西包裹了整个可活动区域 Set the Insets for the sidebar. The sidebar is the thing that displays the score next to you when you play stg, and it wraps the entire movable area.
definitionsLoaders	添加脚本加载器 Add a script loader	append	添加各种Loader，用于加载引擎的脚本。 Add various Loaders for loading engine scripts.

快速上手

⚠ 此段中的Object均指top.kkoishi.stg.common.entities.Object。

本引擎OOP程度较高，基本只需要正确的设置对象和状态即可。 Bootstrapper::initMethod里提供的初始化方法即为您想在最开始时运行的逻辑。

例如：在最开始时显示主菜单，可实现Menu/BaseMenu类，再调用ObjectPool::addUIObject方法把类实例放入（请保证单例性），最后切换gameState为STATE_MENU即可。

不同的gameState需要放入不同的对象，下面是具体说明：

gameState	对象类型	调用方法	说明
STATE_LOADING	任意Object	ObjectPool::addLoadingContent	加载状态
STATE_MENU	任意UIObject	ObjectPool::addUIObject	菜单
STATE_PLAYING	用于表示实体的Object，Bullet，Player，Stage，UIObject

注意事项

如果您需要添加SideBar ，还需要使用Graphics.setUIInsets或者用快速启动类去设置UI边框大小。

需要实现自己的启动流程可以参考Bootstrapper::start方法。

Bootstrapper的initMethod方法会在窗口创建完成后执行传入的lambda表达式或者function，请在里面设置您自己的初始化代码，并且最后切换GenericSystem.gameState 至您需要的状态。

调用Bootstrapper.readEngineSettings()用于读取引擎有关工作目录等的ini文件，请将engines.ini 放在当前目录，然后正确设置工作目录。

默认的engines.ini内容将工作目录定义为jar包所在目录的上一级。

If you need to add SideBar, you also need to use Graphics.setUIInsets or use the Quick Start class to set the UI border size.

If you want to implement your own startup process, you can refer to the Bootstrapper::start method.

Bootstrapper's initMethod method will execute the passed lambda expression or function after the window is created. Please put your own initialization code in it, and finally switch GenericSystem.gameState to the state you need.

Bootstrapper.readEngineSettings() is used to read the ini file of the engine about the working directory, etc. Please put engines.ini in the current directory, and then set the working directory correctly.

The default engines.ini content defines the working directory as the upper level of the directory where the jar package is located.

逻辑

GenericFlags.gameState用于标识当前游戏状态。

当其为GenericFlags.STATE_MENU时，只有ObjectPool .uiObject中的实例会被渲染。

当其为GenericFlags.PLAYING时，ObjectPool中所有对象实例以及player均会被渲染。

您需要做的就是在切换状态之前正确的把实例一股脑丢进去即可。

本引擎提供了一套脚本来加载材质音频等。

实现基本要求的类均位于top.kkoishi.stg.common 包内，（通常）只用继承实现他们的逻辑。

top.kkoishi.stg.common中所有可渲染对象都实现接口top.kkoishi.stg.common.entities.Object，包含更新逻辑、碰撞检测及渲染。

所有实体（Player, Boss, Enemy, Item, Bullet ）都在top.kkoishi.stg.common.entities包内。

上述包内有一些抽象类（以Base/Abstract开头）中）来降低实现难度，而除了Bullet这些类均继承了Entity类。

top.kkoishi.stg.common.ui包负责ui渲染，提供了一系列类来渲染ui，只需要实现并丢进ObjectPool.uiObject。

其余的类为游戏逻辑，包括boss逻辑BossAction、Stage及其逻辑StageAction和类ScreenRenderObject。

引擎整体逻辑为先渲染、然后计算，同时并行播放audio，大体包含四个主要线程InfoSystem、Renderer、GameLoop、AudioPlayer和一个CrashHandle子进程（可选）

🖼 从plugin jar加载并运行

本引擎提供了对plugin的支持，只需要将jar放入plugin_dir即可。

插件的入口类应该实现接口JvmPlugin，并且包含静态方法fun getInstance(): JvmPlugin来获取类实例，或者提供空的构造器。如果这两者均不包含，将会使用sun.misc.Unsafe去强行申请实例。默认寻找插件的目录为engine.ini中workdir下的plugin_dir，如果没有指定，将会在相对引擎本体jar所在文件的目录下的./plugins去寻找。

🔠 按键绑定

KeyBinds类用于管理全局的按键绑定，

🅰 处理程序参数

本引擎提供了Options 类和Option类来快速处理程序参数，实现方式参考了javap的参数处理部分。您只需要将自己的Option用Options::addOption添加到Options中，再调用load方法即可处理程序参数。默认有一个参数-debug用于打开详细日志输出。

(README未完成)

线程异常处理和单一实例

脚本说明

引擎结构

top.kkoishi.stg
             ├─audio - 音频
             ├─boot - 快速启动相关
             │  ├─jvm - 废弃
             │  └─ui - 启动ui
             ├─common - 绝大部分需要继承的抽象类/接口
             │  ├─bullets - 子弹
             │  ├─entities - 实体
             │  └─ui - sidebar menu等ui
             ├─exceptions - 异常及其处理
             ├─gfx - 纹理等渲染逻辑
             ├─localization - 本地化
             ├─logic - 引擎计算逻辑
             │  ├─coordinatespace - 用于优化碰撞
             │  └─keys - 控制全局按键检测
             ├─replay - replay记录播放
             ├─script - 引擎脚本支持
             │  ├─execution - 脚本执行相关
             │  └─reflect - jvm反射
             └─util - 工具类

最后 uuz真的很棒给大家看看

Koishi-Satori/KStg