commit 8fde6e1c8854930298135ab1ba3199ecc54e89d7 Author: shen Date: Sat Sep 12 11:24:43 2026 +0800 chore: establish M0 baseline diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..a2aebd1 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +* text=auto eol=lf +*.bat text eol=crlf +*.jar binary +*.png binary diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..35c749f --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +.gradle/ +.idea/ +.cxx/ +**/.cxx/ +local.properties +build/ +**/build/ +.build/ +.toolchains/ +third_party/sources/ +*.iml +*.keystore +*.jks +*.apk +*.aab +captures/ +OpenJDK17U-jdk_x64_windows_hotspot_17.0.17_10.zip diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..afd5a94 --- /dev/null +++ b/LICENSE @@ -0,0 +1,341 @@ + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..8022eb5 --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +# NESLite + +NESLite 是一个面向 Android 的轻量 NES/FC 模拟器前端。它使用固定版本的 +FCEUmm libretro 内核;当前仓库处于 M0 工程基线阶段。 + +## 快速构建 + +请先阅读 [构建说明](docs/build.md),再执行: + +```powershell +pwsh -NoProfile -File .\tools\check.ps1 -Scope Build +``` + +该命令默认只生成 arm64-v8a 调试 APK,不会运行耐久或实机验收。 + +## 许可证 + +项目在与 FCEUmm 静态链接后须按 GPL-2.0-only 的要求分发。当前许可证和第三方 +通知基线见 [LICENSE](LICENSE) 与 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..61c1a2f --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,24 @@ +# 第三方通知基线 + +本文件列出 M0 已引入、已选定或计划引入的第三方组件。发布包只能包含与实际依赖图一致的条目; +新增或移除组件必须同步更新本文件、`docs/dependencies.md` 和版本锁。 + +## M0 已引入 + +| 组件 | 坐标/版本 | 许可证 | 通知要求 | +| --- | --- | --- | --- | +| AndroidX Core KTX | `androidx.core:core-ktx:1.17.0` | Apache-2.0 | 分发时保留许可和 NOTICE(如上游提供)。 | +| AndroidX Activity KTX | `androidx.activity:activity-ktx:1.12.0` | Apache-2.0 | 分发时保留许可和 NOTICE(如上游提供)。 | + +## 已锁定、尚未引入 + +| 组件 | 固定来源 | 许可证 | 发布时的必需材料 | +| --- | --- | --- | --- | +| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | GPL-2.0-only | 对应完整源码、GPL v2 文本、原始版权/Authors、所有补丁和获取说明。 | +| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | MIT | 原始版权和 MIT 许可文本。 | +| Oboe | 1.10.0 / `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | Apache-2.0 | Apache 2.0 文本及上游 NOTICE(如有)。 | +| Room | 2.7.2 | Apache-2.0 | 实际引入时保留许可/NOTICE。 | +| DataStore | 1.1.7 | Apache-2.0 | 实际引入时保留许可/NOTICE。 | + +测试依赖 JUnit 4.13.2(EPL-1.0)和 AndroidX Test/Espresso(Apache-2.0)不打入生产 APK, +但随测试源码分发时仍需保留其各自的许可证信息。 diff --git a/app/build.gradle.kts b/app/build.gradle.kts new file mode 100644 index 0000000..a4dca0b --- /dev/null +++ b/app/build.gradle.kts @@ -0,0 +1,78 @@ +plugins { + alias(libs.plugins.android.application) + alias(libs.plugins.kotlin.android) +} + +android { + namespace = "org.neslite.app" + compileSdk = 36 + ndkVersion = "28.2.13676358" + + buildFeatures { + buildConfig = true + } + + compileOptions { + sourceCompatibility = JavaVersion.VERSION_17 + targetCompatibility = JavaVersion.VERSION_17 + } + + defaultConfig { + applicationId = "org.neslite.app" + minSdk = 28 + targetSdk = 36 + versionCode = 1 + versionName = "0.0.1-dev" + testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" + + ndk { + abiFilters += "arm64-v8a" + } + + externalNativeBuild { + cmake { + cppFlags += listOf("-std=c++20", "-Wall", "-Wextra", "-Werror") + } + } + } + + buildTypes { + debug { + applicationIdSuffix = ".debug" + versionNameSuffix = "-debug" + } + release { + isMinifyEnabled = false + proguardFiles( + getDefaultProguardFile("proguard-android-optimize.txt"), + "proguard-rules.pro", + ) + } + } + + externalNativeBuild { + cmake { + path = file("src/main/cpp/CMakeLists.txt") + version = "3.22.1" + } + } + + packaging { + jniLibs { + useLegacyPackaging = false + } + } +} + +kotlin { + jvmToolchain(17) +} + +dependencies { + implementation(libs.androidx.core.ktx) + implementation(libs.androidx.activity.ktx) + + testImplementation(libs.junit) + androidTestImplementation(libs.androidx.junit) + androidTestImplementation(libs.androidx.espresso.core) +} diff --git a/app/proguard-rules.pro b/app/proguard-rules.pro new file mode 100644 index 0000000..b6c9081 --- /dev/null +++ b/app/proguard-rules.pro @@ -0,0 +1 @@ +# M0 does not add application-specific shrinker rules. diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml new file mode 100644 index 0000000..483cd16 --- /dev/null +++ b/app/src/main/AndroidManifest.xml @@ -0,0 +1,18 @@ + + + + + + + + + + + diff --git a/app/src/main/cpp/CMakeLists.txt b/app/src/main/cpp/CMakeLists.txt new file mode 100644 index 0000000..6c0ab98 --- /dev/null +++ b/app/src/main/cpp/CMakeLists.txt @@ -0,0 +1,38 @@ +cmake_minimum_required(VERSION 3.22.1) +project(neslite_jni LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) + +set(NESLITE_COMMON_SOURCES + native_smoke.cpp +) + +function(neslite_enable_strict_warnings target) + if(MSVC) + target_compile_options(${target} PRIVATE /W4 /WX) + else() + target_compile_options(${target} PRIVATE -Wall -Wextra -Werror) + endif() +endfunction() + +if(ANDROID) + add_library(neslite_jni SHARED + jni_bridge.cpp + ${NESLITE_COMMON_SOURCES} + ) + neslite_enable_strict_warnings(neslite_jni) + + find_library(log-lib log) + target_link_libraries(neslite_jni PRIVATE ${log-lib}) +else() + enable_testing() + add_executable(neslite_native_smoke_test + tests/native_smoke_test.cpp + ${NESLITE_COMMON_SOURCES} + ) + target_include_directories(neslite_native_smoke_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}) + neslite_enable_strict_warnings(neslite_native_smoke_test) + add_test(NAME neslite_native_smoke_test COMMAND neslite_native_smoke_test) +endif() diff --git a/app/src/main/cpp/jni_bridge.cpp b/app/src/main/cpp/jni_bridge.cpp new file mode 100644 index 0000000..1a30ba0 --- /dev/null +++ b/app/src/main/cpp/jni_bridge.cpp @@ -0,0 +1,11 @@ +#include + +#include + +#include "native_smoke.h" + +extern "C" JNIEXPORT jstring JNICALL +Java_org_neslite_app_NativeBridge_buildInfo(JNIEnv* env, jclass) { + const std::string info = "native protocol v" + std::to_string(neslite::native_protocol_version()); + return env->NewStringUTF(info.c_str()); +} diff --git a/app/src/main/cpp/native_smoke.cpp b/app/src/main/cpp/native_smoke.cpp new file mode 100644 index 0000000..3392e8c --- /dev/null +++ b/app/src/main/cpp/native_smoke.cpp @@ -0,0 +1,9 @@ +#include "native_smoke.h" + +namespace neslite { + +int native_protocol_version() { + return kNativeProtocolVersion; +} + +} // namespace neslite diff --git a/app/src/main/cpp/native_smoke.h b/app/src/main/cpp/native_smoke.h new file mode 100644 index 0000000..c4e5ee8 --- /dev/null +++ b/app/src/main/cpp/native_smoke.h @@ -0,0 +1,8 @@ +#pragma once + +namespace neslite { + +constexpr int kNativeProtocolVersion = 1; +int native_protocol_version(); + +} // namespace neslite diff --git a/app/src/main/cpp/tests/native_smoke_test.cpp b/app/src/main/cpp/tests/native_smoke_test.cpp new file mode 100644 index 0000000..9e9669e --- /dev/null +++ b/app/src/main/cpp/tests/native_smoke_test.cpp @@ -0,0 +1,5 @@ +#include "native_smoke.h" + +int main() { + return neslite::native_protocol_version() == neslite::kNativeProtocolVersion ? 0 : 1; +} diff --git a/app/src/main/java/org/neslite/app/MainActivity.kt b/app/src/main/java/org/neslite/app/MainActivity.kt new file mode 100644 index 0000000..6bf20ec --- /dev/null +++ b/app/src/main/java/org/neslite/app/MainActivity.kt @@ -0,0 +1,30 @@ +package org.neslite.app + +import android.os.Bundle +import android.view.Gravity +import android.widget.LinearLayout +import android.widget.TextView +import androidx.activity.ComponentActivity + +/** M0 骨架页:证明 Kotlin/View 与 JNI 已连通。M1 会将它替换为诊断页面。 */ +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + + val nativeInfo = runCatching { NativeBridge.buildInfo() } + .getOrElse { "JNI unavailable: ${it.javaClass.simpleName}" } + + setContentView( + LinearLayout(this).apply { + gravity = Gravity.CENTER + addView( + TextView(context).apply { + text = getString(R.string.bootstrap_status, nativeInfo) + textSize = 18f + setPadding(48, 48, 48, 48) + }, + ) + }, + ) + } +} diff --git a/app/src/main/java/org/neslite/app/NativeBridge.kt b/app/src/main/java/org/neslite/app/NativeBridge.kt new file mode 100644 index 0000000..5a4f36f --- /dev/null +++ b/app/src/main/java/org/neslite/app/NativeBridge.kt @@ -0,0 +1,10 @@ +package org.neslite.app + +/** JNI boundary. M0 deliberately exposes a build marker, not emulator control. */ +object NativeBridge { + init { + System.loadLibrary("neslite_jni") + } + + external fun buildInfo(): String +} diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml new file mode 100644 index 0000000..4823208 --- /dev/null +++ b/app/src/main/res/values/strings.xml @@ -0,0 +1,4 @@ + + NESLite + NESLite M0 baseline\n%s + diff --git a/app/src/main/res/values/styles.xml b/app/src/main/res/values/styles.xml new file mode 100644 index 0000000..2f74a3c --- /dev/null +++ b/app/src/main/res/values/styles.xml @@ -0,0 +1,7 @@ + + + diff --git a/app/src/test/java/org/neslite/app/BuildIdentityTest.kt b/app/src/test/java/org/neslite/app/BuildIdentityTest.kt new file mode 100644 index 0000000..df1f17f --- /dev/null +++ b/app/src/test/java/org/neslite/app/BuildIdentityTest.kt @@ -0,0 +1,12 @@ +package org.neslite.app + +import org.junit.Assert.assertEquals +import org.junit.Test + +class BuildIdentityTest { + @Test + fun debugBuildUsesTheDocumentedIdentity() { + assertEquals("org.neslite.app.debug", BuildConfig.APPLICATION_ID) + assertEquals("0.0.1-dev-debug", BuildConfig.VERSION_NAME) + } +} diff --git a/build.gradle.kts b/build.gradle.kts new file mode 100644 index 0000000..7629126 --- /dev/null +++ b/build.gradle.kts @@ -0,0 +1,4 @@ +plugins { + alias(libs.plugins.android.application) apply false + alias(libs.plugins.kotlin.android) apply false +} diff --git a/design.md b/design.md new file mode 100644 index 0000000..4b853cb --- /dev/null +++ b/design.md @@ -0,0 +1,584 @@ +可以。针对你的 **Honor MagicOS 10 手机+小鸡 X5 Lite 手柄**,建议把项目正式定义为: + +> **NESLite Android:采用 FCEUmm 模拟内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。** + +开发路线固定为: + +**先验证手机与手柄 → 接通模拟内核 → 完成音画同步 → 完善手柄操作 → 建立可靠存档 → 完善界面与系统适配 → 回归测试和发布。** + +荣耀官方资料将 MagicOS 10 列为基于 Android 16,因此首要适配目标按 **Android 16/API 36**设置;具体手机的处理器架构、屏幕刷新率和内存页大小,由首个诊断版本读取,不预先猜测。 + +下面给出完整的实施计划。**所列版本是开发里程碑,性能和稳定性指标是验收目标,并非已经完成的实测结果。** + +--- + +# 一、先冻结 V1.0 的功能范围 + +第一版的目标不是做一个功能庞大的“全能模拟器”,而是: + +> **在你的手机上,插入 X5 Lite、选择游戏即可稳定游玩,声音正常、操作准确、进度不会轻易丢失。** + +## 1. V1.0 必须具备的功能 + +| 功能领域 | V1.0 范围 | +|---|---| +| 游戏支持 | NES/FC 卡带游戏,优先支持 `.nes` 文件;识别 iNES、NES 2.0 文件头,具体卡带兼容性以内核和测试结果为准 | +| 游戏导入 | 通过 Android 系统文件选择器导入,支持中文文件名和重复文件识别 | +| 游戏管理 | 游戏列表、搜索、最近游玩、收藏、从列表移除 | +| 游戏运行 | 启动、暂停、继续、重置、退出游戏 | +| 图像显示 | 横屏、保持显示比例、整数缩放、最近邻/线性过滤切换 | +| 音频 | 正常声音输出、音量控制、静音、音画同步 | +| 手柄 | X5 Lite 优先适配,兼容 Android 标准手柄输入 | +| 按键设置 | 默认映射、A/B 交换、自定义绑定、摇杆死区、A/B 连发 | +| 存档 | 游戏自身存档、即时存档、自动恢复点、存档导入导出 | +| 系统适配 | 后台暂停、锁屏暂停、手柄断开处理、界面重建和音频设备变化处理 | +| 无手柄操作 | 基础虚拟方向键、A/B、Start、Select | +| 诊断 | 手柄测试、运行状态、错误日志、诊断信息导出 | + +FCEUmm 已提供卡带存档、即时存档和多种卡带 Mapper 支持,但**内核支持某项功能,不等于我们编写的 Android 前端已经完成该功能**,仍需要逐项接入和验证。 + +## 2. V1.0 暂不纳入的功能 + +暂不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、提前运行降低延迟(run-ahead),也不在第一版开放用户自行下载和切换内核。 + +**FDS 磁碟机、光枪、四人适配器以及第二只手柄的完整体验,放到 V1.1 之后。** FDS 还涉及额外固件文件,因此不与普通 `.nes` 卡带游戏混在首版范围中。 + +--- + +# 二、技术方案与工程基线 + +## 1. 推荐技术组合 + +| 模块 | 建议选择 | 设计目的 | +|---|---|---| +| 应用语言 | Kotlin | 界面、系统交互、文件导入、手柄事件 | +| 界面框架 | AndroidX+原生 View | 首版减少框架复杂度,方便处理游戏界面焦点 | +| 模拟内核 | FCEUmm,固定上游提交版本 | 不从零开发 NES CPU、PPU、APU 和 Mapper | +| 内核接口 | libretro | 将内核与音视频、输入、存档管理分离 | +| 原生运行层 | C/C+++Android NDK | 内核调用、缓冲、时钟和渲染适配 | +| Kotlin/C++ 连接 | JNI | 传递控制命令、输入状态和界面生命周期事件 | +| 图像输出 | `GLSurfaceView`+OpenGL ES | 显示内核输出,完成缩放和比例控制 | +| 音频输出 | Oboe | 低延迟音频与设备差异处理 | +| 游戏索引 | Room | 保存游戏元数据、最近游玩和收藏状态 | +| 应用设置 | DataStore | 保存显示、音频和操作偏好 | +| 构建 | Gradle+CMake/必要的上游构建适配 | 可重复构建,避免手工复制不明来源的 `.so` | + +这里采用的是**自己编写轻量 libretro 前端**,不是修改整个 RetroArch 界面。libretro 允许内核以静态库或动态库形式被前端调用,因此首版可把内核固定打包到应用中。 + +## 2. SDK 和工具链建议 + +建议采用以下保守起点,而不是为了“最新”频繁更换构建工具: + +```text +最低系统:Android 9 / API 28 +主要目标:Android 16 / API 36 + +minSdk:28 +compileSdk:36 +targetSdk:36 + +发布架构:arm64-v8a +测试架构:按测试环境增加 x86_64 + +AGP:8.13.2 +Gradle:8.13 +JDK:17 +NDK:r28 或更新的稳定版本,工程中锁定精确版本 +``` + +AGP 8.13 系列支持 API 36,官方兼容表给出的 Gradle 和 JDK 基线分别为 8.13、17;这里是针对目标系统选择的构建组合,不是在宣称它是当前最新版本。 + +**NDK 不沿用旧工程里随机留下来的版本。** Android 官方说明,NDK r28 及以上默认采用 16 KB 对齐;同时还需要检查最终 APK 中的原生库打包对齐、第三方依赖和运行时代码。不能只升级 NDK,就认为整个应用已经验证通过。 + +所有依赖都应锁定具体版本,FCEUmm 额外记录 **Git commit、构建选项和本地补丁**,禁止使用会自动变化的依赖版本。 + +--- + +# 三、软件架构:界面与模拟执行严格分开 + +## 1. 总体结构 + +```text +NESLite Android +│ +├── 应用界面 +│ ├── 游戏列表 +│ ├── 游戏画面与暂停菜单 +│ ├── 按键映射 +│ ├── 存档管理 +│ └── 设置与诊断 +│ +├── Android 平台适配 +│ ├── 手柄事件与设备监听 +│ ├── 系统文件选择器 +│ ├── Activity / Surface 生命周期 +│ └── 音频焦点与设备变化 +│ +├── JNI 桥接 +│ ├── 加载 / 暂停 / 重置 / 退出命令 +│ ├── 输入状态更新 +│ └── 错误和运行状态回传 +│ +├── 原生运行引擎 +│ ├── LibretroHost +│ ├── EmulationLoop +│ ├── VideoRenderer +│ ├── AudioEngine +│ ├── InputSnapshot +│ └── SaveStateManager +│ +└── 固定版本 FCEUmm +``` + +## 2. 线程职责 + +建议从第一版就明确线程所有权,避免后面靠大量锁修补。 + +| 线程或执行环境 | 允许处理的工作 | 不应处理的工作 | +|---|---|---| +| Android 主线程 | 界面、输入事件、发送控制命令 | 执行模拟、写大文件、等待内核长时间返回 | +| 模拟线程 | 调用内核、读取输入快照、生成图像和声音、取得存档快照 | 操作 Android 界面、直接进行耗时文件写入 | +| GL 渲染线程 | 上传图像、计算显示区域、提交画面 | 修改内核状态 | +| 音频回调线程 | 从音频缓冲读取数据并输出 | 文件操作、等待互斥锁、动态分配大量内存、执行模拟内核 | +| 文件工作线程 | 导入游戏、写存档、导出诊断 | 直接读取正在变化的内核内存 | + +**所有改变内核状态的调用统一在模拟线程执行。** 例如,用户点击“读档”,界面只提交命令,由模拟线程在合适的帧边界执行,而不是从主线程直接调用 `retro_unserialize()`。 + +Oboe 官方特别要求低延迟音频回调避免阻塞、文件读写和内存分配,因此音频线程必须与模拟执行和存档写盘解耦。 + +--- + +# 四、分版本开发路线 + +建议采用 **0.1.x → 0.2.x → … → 0.9.x → 1.0.0** 的递进路线。每个阶段都有可安装 APK 和明确验收结果,不以“代码已经写完”作为完成标准。 + +## 阶段 0.1.x:工程基线与 X5 Lite 诊断 + +**目标:先证明手机能稳定加载原生库、接收真实手柄输入。** + +| 小版本 | 工作内容 | +|---|---| +| 0.1.0 | 建立 Android+JNI 工程;读取系统版本、ABI、屏幕信息;验证原生库加载 | +| 0.1.1 | 枚举输入设备,显示设备名称、厂商/产品标识、输入源和轴信息 | +| 0.1.2 | 显示所有按钮按下/松开事件、方向键、摇杆和扳机事件 | +| 0.1.3 | 增加热插拔、失焦清理、诊断导出,形成 X5 Lite 初始输入档案 | + +**交付物:** 手柄诊断 APK、设备诊断 JSON、X5 Lite 实测键位表。 + +**验收条件:** 在你的手机上,方向和 A/B 能同时按下;松开后状态归零;拔出手柄不会残留按键;重连后能够继续检测。 + +这一阶段没有必要先做漂亮的游戏列表,也不需要游戏 ROM。 + +## 阶段 0.2.x:接通 FCEUmm,形成基础游戏运行链路 + +**目标:能够导入并运行游戏,看到正确画面,并用手柄操作。** + +| 小版本 | 工作内容 | +|---|---| +| 0.2.0 | 固定 FCEUmm 提交版本,完成 NDK 编译和 libretro 接口封装 | +| 0.2.1 | 完成 `.nes` 导入、文件头检查、内部存储和 ROM 加载 | +| 0.2.2 | 接通视频回调、像素格式处理、OpenGL 显示和基础缩放 | +| 0.2.3 | 将 0.1.x 的输入接入内核,实现启动、暂停、重置和退出 | + +**交付物:** 基础运行 APK、内核构建记录、首批游戏兼容清单。 + +**验收条件:** 至少通过一组合法测试 ROM,并能完成“加载—运行—暂停—继续—重置—退出—重新加载”的完整流程。 + +此时必须接入 libretro 的环境回调、配置选项和目录等必要能力,不能只实现 `retro_run()`,然后把所有其他请求都当作成功。libretro 的环境回调用于内核与前端协商能力,错误的调用顺序也可能导致未定义行为。 + +## 阶段 0.3.x:声音、帧率和音画同步 + +**目标:从“游戏能动”提升到“游戏速度正确、声音连续”。** + +| 小版本 | 工作内容 | +|---|---| +| 0.3.0 | 接入 Oboe 和音频环形缓冲 | +| 0.3.1 | 实现音频设备实际采样率与内核采样率之间的适配 | +| 0.3.2 | 完成模拟时钟、视频显示节奏、缓冲水位控制 | +| 0.3.3 | 实现静音、音频焦点处理、设备切换和诊断统计 | + +**交付物:** 音画完整的可玩 APK、帧时间与音频缓冲统计。 + +**验收条件:** 连续游玩测试中没有持续爆音、越玩声音越滞后、游戏速度逐渐偏移等问题;暂停后声音停止,恢复后没有旧声音积压播放。 + +## 阶段 0.4.x:完成 X5 Lite 的实际操作体验 + +**目标:不只是能接收按键,而是可以只靠手柄完成主要操作。** + +| 小版本 | 工作内容 | +|---|---| +| 0.4.0 | 默认映射、A/B 交换、自定义绑定 | +| 0.4.1 | 摇杆死区、方向冲突处理、输入去重 | +| 0.4.2 | A/B 连发、暂停菜单、可配置快捷功能 | +| 0.4.3 | 手柄导航游戏列表和菜单,持久化控制器档案 | + +**交付物:** X5 Lite 配置、手柄操作说明、按键回归报告。 + +**验收条件:** 从游戏列表进入游戏、暂停、选择存档、继续和退出,都能通过手柄完成,不依赖频繁触屏。 + +## 阶段 0.5.x:可靠存档与恢复 + +**目标:保护进度,避免“游戏可以玩,但是不敢退出”。** + +| 小版本 | 工作内容 | +|---|---| +| 0.5.0 | 游戏自身存档读取、变化检测和安全写盘 | +| 0.5.1 | 即时存档、读档、槽位和缩略图 | +| 0.5.2 | 自动恢复点、备份轮换、损坏检测 | +| 0.5.3 | 存档导入导出、跨版本检查和失败恢复 | + +**交付物:** 存档格式说明、故障测试报告、可导出的存档包。 + +**验收条件:** 正常退出后可恢复;存档文件截断时有明确错误;写盘失败不覆盖最后一个有效存档;不同 ROM 不会互相覆盖进度。 + +## 阶段 0.6.x:完善日常使用界面 + +**目标:形成可以长期使用的完整应用。** + +| 小版本 | 工作内容 | +|---|---| +| 0.6.0 | 游戏列表、搜索、收藏、最近游玩 | +| 0.6.1 | 显示、音频、手柄设置 | +| 0.6.2 | 存档管理页面、游戏信息和错误提示 | +| 0.6.3 | 基础虚拟按键、首次使用引导和无手柄操作 | + +**验收条件:** 首次安装后,用户能够完成“导入游戏—连接手柄—开始游戏—保存—退出”,不需要理解内部目录和 libretro 概念。 + +## 阶段 0.7.x:MagicOS 10 专项适配 + +**目标:处理系统行为,而不是只验证应用一直停留在前台的情况。** + +主要测试返回手势、横屏安全区域、锁屏与解锁、通知和来电、音频设备变化、应用切换、Surface 重建、不同刷新率,以及手柄接入状态变化。 + +**交付物:** MagicOS 10 专项兼容报告。 + +**验收条件:** 不出现后台继续发声、返回键误退出、恢复后黑屏、手柄失效或者输入卡住等问题。 + +## 阶段 0.9.x:回归、性能和发布准备 + +完成批量兼容测试、长时间运行测试、原生崩溃定位、16 KB 兼容检查、升级安装测试、许可证整理和发布签名。 + +**交付物:** 候选发布 APK、对应源码、构建说明、测试报告和已知问题清单。 + +## 阶段 1.0.0:正式可用版本 + +只有在前述关键门槛全部通过后,才标记为 1.0.0。 + +**1.0.0 表示规定范围内可用且经过验证,不表示支持所有历史卡带、所有改版 ROM 或所有安卓设备。** + +--- + +# 五、X5 Lite 适配的具体设计 + +## 1. 使用原生安卓模式 + +X5 Lite 应使用 **深蓝色指示灯的安卓模式**。官方说明,“视图+菜单”长按约 2 秒用于切换连接模式,部分手机还需要开启 OTG。 + +因此本项目明确: + +**不依赖 G-Touch 触屏映射,不把“视图+菜单长按”设置成模拟器快捷键,也不把厂商功能键作为唯一的菜单入口。** + +## 2. 默认按键映射 + +下面是应用层的建议映射,实际 Android 键码由 0.1.x 实测后绑定。 + +| 手柄操作 | 游戏内默认功能 | +|---|---| +| 十字方向键 | NES 上、下、左、右 | +| 左摇杆 | 可选的 NES 方向控制 | +| A | NES A | +| B | NES B | +| X | NES A 连发 | +| Y | NES B 连发 | +| 菜单键 | NES Start | +| 视图键 | NES Select | +| 右摇杆按下 | 打开/关闭暂停菜单 | +| RB | 按住快进,可关闭 | +| 其他肩键/扳机 | 默认保留,允许用户自定义 | + +**快速读档默认不绑定一个容易误触的单键。** 读档会改变当前进度,首版更适合放在暂停菜单内,或要求用户主动配置快捷键。 + +X5 Lite 本身支持连发和按键布局交换,所以适配不能只根据按钮上的字母推断输入;测试时应先关闭手柄硬件连发,避免它与软件连发叠加。 + +## 3. 输入层必须处理的细节 + +Android 手柄的按钮和轴分别通过 `KeyEvent`、`MotionEvent` 上报;方向键可能是按键事件,也可能是 HAT 轴,部分扳机还可能同时上报轴和按钮事件。 + +据此,输入模块按以下规则设计: + +**状态而不是点击。** NES 输入保存为“当前哪些按钮被按住”,正确支持方向+跳跃+攻击等组合。 + +**同一动作去重。** 同一个扳机同时上报轴和按钮时,不能让菜单动作触发两次。 + +**不同来源分别维护。** 手柄、摇杆和虚拟按键先保存各自状态,再合成为游戏输入,避免松开一个来源时错误释放另一个仍按住的来源。 + +**方向冲突有确定规则。** 首版建议左右同时按下时横向归零,上下同理;摇杆阈值采用按下/释放不同阈值,减少边界抖动。 + +**异常状态主动清理。** 手柄断开、应用失去游戏交互状态或进入暂停菜单时,清空相应输入,恢复后重新采样。 + +**配置与临时设备编号分离。** 控制器配置使用设备特征和实际按键档案匹配,连接时的设备编号只用于当前会话。 + +--- + +# 六、几个决定软件质量的实现细节 + +## 1. 模拟帧率不能写死成手机刷新率 + +FCEUmm 文档列出的 NTSC 运行频率约为 **60.10 帧/秒**,PAL/Dendy 约为 **50 帧/秒**;实际执行应读取内核返回的时序信息。 + +因此不能采用: + +```text +手机每刷新一次 → 执行一帧游戏 +``` + +也不能简单循环 `sleep(16)`。 + +建议采用: + +```text +模拟线程:按照内核时序和音频缓冲状态执行 +渲染线程:按照屏幕显示节奏显示最新可用画面 +音频线程:按照音频设备请求消耗声音数据 +``` + +正常模式由音频输出节奏和缓冲水位参与调节;音频不可用、测试模式和快进模式另有明确的时钟策略。 + +**丢弃过时的待显示画面,不等于跳过内核执行。** 两者必须区分,否则可能改变游戏速度和逻辑。 + +## 2. 不通过界面层搬运每一帧画面 + +建议在原生层保存图像缓冲,并交给 GL 线程显示,不要每帧创建新的 `Bitmap`,再通过界面状态更新显示。 + +视频适配必须处理内核给出的像素格式、宽高和行跨度 `pitch`,不假定每行一定是“宽度×固定字节数”;缓冲交接也不能保存一个已失效的内核临时指针。 + +显示设置将“4:3 显示”和“原始像素整数缩放”分开,避免为了铺满手机屏幕把画面强行拉宽。 + +## 3. 音频缓冲需要可测、可调 + +Oboe 支持请求低延迟和独占模式,但请求不一定能得到满足,程序需要检查实际打开的音频流参数并提供回退。 + +本项目建议记录: + +```text +内核输出采样率 +音频设备实际采样率 +每次回调请求的帧数 +音频缓冲水位 +缓冲不足次数 +音频流重建次数 +``` + +先实现稳定的默认配置,再增加低延迟配置。不能把“缓冲设得最小”直接当成优化完成,也不能把环形缓冲长度当作全部端到端音频延迟。 + +## 4. 游戏导入后使用内部稳定副本 + +Android 系统文件选择器提供的是文档 URI,应该通过相应文件接口读取,不能把 `content://...` 当作普通文件路径交给 C 的文件函数。Storage Access Framework 可以让用户授权访问选定文件,而不要求应用取得整个存储空间的访问权限。 + +建议导入流程: + +```text +用户选择文件 + ↓ +检查大小、文件头和读取结果 + ↓ +复制到应用内部文件目录中的临时文件 + ↓ +计算 SHA-256 + ↓ +校验并提交正式 ROM 文件 + ↓ +建立游戏索引 +``` + +ROM 的身份使用内容哈希,而不是文件名。这样同一游戏改名后可以识别为重复文件,不同游戏即使同名,也不会共用存档。 + +复制后的正式 ROM 放在应用内部文件目录,**不放在可能被清理的缓存目录**。 + +## 5. 游戏存档与即时存档分开管理 + +libretro 分别提供保存内存访问和状态序列化接口;即时存档不是简单复制游戏的电池存档。 + +建议采用以下数据策略: + +| 类型 | 建议策略 | +|---|---| +| 游戏自身存档 | 检查内容变化,周期性提交;暂停和正常退出时补充提交 | +| 手动即时存档 | 10 个槽位,附带时间和缩略图 | +| 自动恢复点 | 独立于手动槽位,保留最近 3 份 | +| 覆盖保护 | 新文件校验成功后再替换,保留上一份有效备份 | +| 导出 | 使用系统文件选择器,默认不把 ROM 混入存档包 | + +即时存档元数据至少记录: + +```text +ROM 内容哈希 +内核名称和提交版本 +存档封装格式版本 +相关内核配置 +创建时间 +数据长度 +数据校验值 +``` + +**不承诺跨 FCEUmm 版本即时存档自动兼容。** 升级时保留原文件,先验证再恢复;读档失败后,应恢复之前的有效状态或安全重新加载,不能继续运行一个可能已被部分修改的内核状态。 + +另外,读入较早的即时存档可能回退游戏进度,因此建议在读档前保留当前游戏存档备份。 + +## 6. 自动保存不等于不会丢失任何进度 + +设计上可以初步采用“游戏存档变化后周期性提交、即时恢复点定期生成”的策略,但应用被强制停止或进程突然终止时,不应依赖退出回调完成最后一次保存。 + +验收目标应表述为: + +> **最近已经成功提交的存档保持有效;突然终止时可能丢失最后一次提交之后的进度,但不能把此前有效存档也破坏。** + +--- + +# 七、MagicOS 10/Android 16 专项适配 + +## 1. 16 KB 原生库兼容 + +需要检查 FCEUmm、JNI 运行层、音频依赖和 C++ 运行库,以及最终 APK 的打包结果。 + +诊断阶段可通过以下命令读取实际设备页大小: + +```bash +adb shell getconf PAGE_SIZE +``` + +这是 Android 官方给出的检查方式。即使你的手机当前使用 4 KB 页,也应在支持 16 KB 的测试环境中验证原生库,不能由系统名称推断页大小。 + +## 2. 返回导航与全面屏布局 + +Android 16 对目标 API 36 的应用启用新的返回导航行为,旧式 `onBackPressed()` 和仅拦截 `KEYCODE_BACK` 的做法不再可靠;同时需要处理全面屏布局,不能依靠旧的退出 edge-to-edge 开关。 + +本项目建议统一规定: + +```text +游戏运行中返回 → 打开暂停菜单 +暂停菜单中返回 → 继续游戏 +设置页面返回 → 返回上一级 +游戏列表中返回 → 正常退出应用 +``` + +游戏画面和菜单分别计算安全区域,避免按钮落在挖孔、系统栏或手势边缘。 + +## 3. 生命周期与后台行为 + +首版明确选择:**切到后台就暂停,不做后台继续模拟。** + +锁屏、应用切换或失去音频焦点时,按策略暂停内核、停止声音、清空输入,并请求存档提交。回到前台后先恢复画面和音频资源,再由用户继续游戏。 + +不把“关闭系统所有省电机制”作为正常运行前提,也不为了保活引入与模拟器无关的后台服务。 + +## 4. 系统回收与异常恢复 + +启动时检查上一会话是否异常结束。若某 ROM 或即时存档连续导致崩溃,下一次启动不自动重开它,而是进入游戏列表并提示恢复选择,避免形成启动即崩溃的循环。 + +--- + +# 八、测试与验收体系 + +建议把测试分成 **内核接入、手柄、系统、存档和性能** 五类,并保存可复现记录。 + +| 测试类别 | 重点场景 | 建议验收要求 | +|---|---|---| +| 安装与升级 | 首次安装、覆盖升级、重新启动 | 能安装运行,升级不误删游戏和存档 | +| 文件导入 | 中文名、同名不同内容、重复内容、损坏文件 | 不误覆盖,有清楚的失败提示 | +| 卡带兼容 | 常见 Mapper、不同区域时序、游戏存档 | 通过规定测试集合,记录不支持项 | +| 基础输入 | 方向+A/B、多键同时按、长按 | 无漏释放和重复菜单触发 | +| 热插拔 | 游戏中拔出、重连、待机唤醒 | 自动进入安全状态,重连后可继续 | +| 生命周期 | 锁屏、切后台、返回前台、Surface 重建 | 无持续黑屏、后台声音和输入卡住 | +| 存档 | 保存、读取、覆盖、损坏、磁盘不足 | 失败不破坏最后一份有效文件 | +| 进程终止 | 强制停止后启动 | 可以找到最近已提交的有效恢复点 | +| 音频 | 长时间运行、暂停恢复、设备切换 | 无持续爆音和累积性音画偏移 | +| 显示 | 不同刷新率、不同显示比例 | 游戏速度不随屏幕刷新率改变 | +| 原生兼容 | 4 KB/16 KB 环境 | 原生库正确加载并通过运行测试 | + +## 建议的量化目标 + +这些指标在拿到实机数据后可以调整,但应提前定义测量方法。 + +| 指标 | 初始目标 | +|---|---| +| 正常速度 | 长时间平均模拟速度保持在目标速度的 99.5%~100.5% | +| 核心稳定性 | 代表性游戏连续运行 2 小时,无崩溃、ANR 和持续内存增长 | +| 输入可靠性 | 自动测试序列和人工组合输入测试中无残留按键 | +| 软件侧输入延迟 | 正常负载下,从应用收到输入到内核采样的 P95 不超过约一个模拟帧 | +| 存档可靠性 | 连续 100 次存读档测试通过;故障注入不损坏已提交备份 | +| 热插拔 | 20 轮断开与重连后仍可正常操作 | +| 后台恢复 | 20 轮切换与恢复后没有声音、画面或输入异常 | + +**软件侧输入延迟不等于按键到屏幕的总延迟。** 手柄传输、系统事件分发、游戏自身响应和显示扫描都在完整链路中;端到端延迟应另行实测,不预先宣称“零延迟”。 + +测试 ROM 只使用自制或有权使用的样本;对需要随源码分发的测试文件,额外核对再分发许可。 + +--- + +# 九、项目目录与交付要求 + +建议仓库保持简单,不在第一版拆出大量独立工程: + +```text +NESLite/ +├── app/ +│ └── src/main/ +│ ├── java/.../ +│ │ ├── ui/ +│ │ ├── input/ +│ │ ├── storage/ +│ │ └── diagnostics/ +│ ├── cpp/ +│ │ ├── jni/ +│ │ ├── core_host/ +│ │ ├── engine/ +│ │ ├── video/ +│ │ ├── audio/ +│ │ └── state/ +│ └── res/ +├── third_party/ +│ ├── fceumm/ +│ ├── libretro/ +│ └── oboe/ +├── tests/ +│ ├── input/ +│ ├── state/ +│ ├── compatibility/ +│ └── lifecycle/ +├── scripts/ +├── docs/ +│ ├── requirements.md +│ ├── architecture.md +│ ├── build.md +│ ├── controller-x5lite.md +│ ├── save-format.md +│ └── acceptance.md +└── THIRD_PARTY_NOTICES +``` + +每个里程碑都应交付 **可安装 APK、对应源码提交、构建说明、验收记录和已知问题**。发布版还应保存原生符号文件,以便定位 C/C++ 崩溃。 + +FCEUmm 文档和仓库声明使用 GPLv2,因此本计划默认采用 **GPL 兼容的源码交付/发布方式**。对外分发时应处理对应源码、版权和许可证义务;libretro 接口头文件的许可证不会替代 FCEUmm 的许可证。 + +--- + +# 十、最先实施的工作 + +**下一步应直接实施 0.1.x,而不是先编写所有模拟器功能。** + +第一轮工程只需要做到: + +```text +能安装到你的 MagicOS 10 手机 + ↓ +能加载一个测试原生库 + ↓ +能识别 X5 Lite 并实时显示所有输入 + ↓ +能验证组合键、松开、拔出与重连 + ↓ +能导出设备与按键诊断 +``` + +这一步完成后,就能把目前尚未实测的“应该可以适配”,转化成有依据的 **手机环境基线+X5 Lite 输入规范**。随后在 **0.2.x 接通 FCEUmm、0.3.x 完成声音与正确运行速度**,形成第一版真正可玩的原型;再用 **0.4.x~0.7.x** 把它做成操作顺手、存档可靠、适应 MagicOS 10 系统行为的日常应用。 \ No newline at end of file diff --git a/docs/acceptance.md b/docs/acceptance.md new file mode 100644 index 0000000..389670a --- /dev/null +++ b/docs/acceptance.md @@ -0,0 +1,26 @@ +# 验收入口与报告约定 + +## L 级别入口 + +| 级别 | 用途 | 本地入口/报告 | +| --- | --- | --- | +| L0 | 文档、清单、版本和材料核对 | 人工核对,记录在阶段报告 | +| L1 | 单项逻辑、构建、解析器或映射 | `tools/check.ps1 -Scope Local` 或 `-Scope Module`,按项追加最小用例 | +| L2 | 模块交接、JNI、文件、UI 或设备 | 相邻模块路径;需要设备时记录实机证据 | +| L3 | G0~G7 阶段出口 | `tools/check.ps1 -Scope Stage` 加当阶段指定路径和 H 项 | +| L4 | M8/G8 候选发布 | 冻结兼容集和有效 H 项索引 | + +默认命令只做 M0 有界验证;不会启动 ROM 集、30 分钟音画、100 次存读档、20 轮插拔/生命周期、 +2 小时长测或 1,000 次延迟采样。 + +## H 专项编号 + +`H-AV` 音画与速度、`H-HOT` 插拔、`H-SAVE` 存档、`H-LIFE` 生命周期、`H-LONG` 长稳、 +`H-INPUT` 软件输入延迟、`H-NATIVE` 原生兼容、`H-UPGRADE` 覆盖升级。它们按 `todo.md` 的首次 +执行节点和固定口径实施;本文件不改变数量或通过标准。 + +## 报告模板 + +每个阶段在 `docs/reports/` 用 [阶段报告模板](reports/phase-report-template.md) 建立一份 +报告。它必须包含源码提交、内核/依赖锁、设备和系统、ROM 哈希、参数、命令、结果、日志和已知 +问题。M0 的实际结果写入 [m0-baseline.md](reports/m0-baseline.md)。 diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..cacacd7 --- /dev/null +++ b/docs/build.md @@ -0,0 +1,46 @@ +# NESLite 可复现构建说明 + +本说明对应 M0 基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、 +FCEUmm 或 Oboe 文件。 + +## 前置条件 + +1. 安装或使用 [toolchain.md](toolchain.md) 中的 JDK 17.0.17+10、SDK Platform 36.1、 + NDK 28.2.13676358 与 Android CMake 3.22.1。 +2. 设置 `JAVA_HOME` 指向 JDK 17;不能用系统默认的 JDK 21。 +3. 设置 `ANDROID_HOME`(或在未设置时使用本机记录的 SDK 根目录)。`local.properties` 仅保存 + 本机 `sdk.dir`,不提交。 +4. 首次构建需要访问 Google Maven、Maven Central 与 Gradle 分发服务,以取得已锁定版本。 +5. 若 M2/M3 需要上游源码,运行: + + ```powershell + .\tools\fetch-third-party.ps1 + ``` + + 该脚本根据 `third_party/manifest.json` 检出固定提交;M0 的 JNI stub 不依赖这些源码。 + +## 构建调试 APK + +```powershell +pwsh -NoProfile -File .\tools\check.ps1 -Scope Build +``` + +产物为 `app/build/outputs/apk/debug/app-debug.apk`,其中只包含 `arm64-v8a` 的 +`libneslite_jni.so`。调试包的 application ID 是 `org.neslite.app.debug`。 + +## 有界检查入口 + +| 命令 | 范围 | 不会执行 | +| --- | --- | --- | +| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Build` | 生成调试 APK | 单元、原生、实机、长测 | +| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Local` | Kotlin 本地单元测试 | APK、原生、实机、长测 | +| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Module` | 原生 smoke test 与 Kotlin 本地单测 | APK、实机、长测 | +| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Stage` | M0 构建加上述有界测试 | 设备、耐久、H 专项 | + +`Stage` 是 M0 的阶段入口,不是未来 G1~G9 的替代。实机、ROM、存档、插拔和耐久验收必须在 +相应里程碑按 [acceptance.md](acceptance.md) 执行和记录。 + +## 清理 + +只清理本工程生成物时删除 `build/`、`app/build/` 和 `.build/`;不要删除 SDK、NDK、 +`.toolchains/` 或用户的签名密钥。上述输出均已被 Git 忽略。 diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..be88870 --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,22 @@ +# 依赖、获取与许可证说明 + +本页是人可读的依赖清单;精确 Git 锁见 [third_party/manifest.json](../third_party/manifest.json), +Gradle 版本锁见 [gradle/libs.versions.toml](../gradle/libs.versions.toml)。任何新增依赖必须同时更新 +这两处之一、[THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md) 和本页。 + +| 组件 | 固定版本/提交 | 获取方式 | 许可证/交付材料 | 状态 | +| --- | --- | --- | --- | --- | +| Android Gradle Plugin | 8.13.2 | Gradle Plugin Portal | Apache-2.0;发布材料列出坐标 | M0 使用 | +| Kotlin Gradle plugin | 2.3.0 | Gradle Plugin Portal | Apache-2.0;发布材料列出坐标 | M0 使用 | +| AndroidX Core/Activity | 1.17.0/1.12.0 | Google Maven | Apache-2.0;保留 notices | M0 使用 | +| JUnit | 4.13.2 | Maven Central | EPL-1.0;测试依赖,不打入生产 APK | M0 使用 | +| AndroidX test/Espresso | 1.3.0/3.7.0 | Google Maven | Apache-2.0;测试依赖,不打入生产 APK | M0 使用 | +| Room | 2.7.2 | Google Maven | Apache-2.0;后续 APK notices | M2 预锁定 | +| DataStore | 1.1.7 | Google Maven | Apache-2.0;后续 APK notices | M4/M6 预锁定 | +| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | `tools/fetch-third-party.ps1` | GPL-2.0-only;交付完整对应源码、COPYING、修改说明 | M2 预锁定 | +| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | `tools/fetch-third-party.ps1` | MIT;保留版权及许可 | M2 预锁定 | +| Oboe | 1.10.0 / `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | `tools/fetch-third-party.ps1` | Apache-2.0;保留 notices | M3 预锁定 | + +本项目计划静态链接 GPL-2.0-only 的 FCEUmm;因此将应用和可分发的对应源码按 +GPL-2.0-only 处理。发布前必须由发行负责人核对依赖的实际引入图、完整许可文本、版权声明、 +修改源和源码提供义务;M0 的清单不构成法律意见。 diff --git a/docs/development_plan_V1.0.md b/docs/development_plan_V1.0.md new file mode 100644 index 0000000..97de2b2 --- /dev/null +++ b/docs/development_plan_V1.0.md @@ -0,0 +1,435 @@ +# NESLite V1.0 开发计划 + +| 项目 | 内容 | +| --- | --- | +| 产品名称 | NESLite | +| 文档版本 | V1.0 | +| 编制日期 | 2026-09-12 | +| 需求依据 | [design.md](../design.md) | +| 目标版本 | Android 应用 1.0.0 | +| 首要设备 | 用户的 Honor MagicOS 10 手机+小鸡 X5 Lite 手柄 | +| 当前状态 | 规划完成,开发尚未开始;编制前目录仅有设计文档,尚无 Android 工程,也未初始化 Git 仓库 | + +本计划将 `design.md` 转化为可执行的任务、阶段依赖、交付物和验收门槛。产品范围以设计文档为准;工期、实现默认值和测试样本数量属于本计划提出的执行基线,尚无实机测试结果。文档版本 V1.0 不代表应用已经达到 1.0.0。 + +## 1. 开发目标与范围 + +### 1.1 交付目标 + +交付一款采用固定版本 FCEUmm 内核、自研 Android 前端、原生手柄输入的轻量 NES/FC 模拟器。用户能够完成“导入游戏 → 连接手柄 → 开始游戏 → 暂停和存档 → 退出 → 恢复进度”,并在目标手机上获得稳定的速度、声音和操作体验。 + +第一版复用内核的 CPU、PPU、APU 和 Mapper 实现,开发重心为 Android 适配、libretro 宿主、音视频调度、输入和数据可靠性。所有内核能力均需经过前端接入和测试才能算作产品功能。 + +### 1.2 需求与阶段对应表 + +下列项目均为 V1.0 范围;“完成阶段”指功能闭环,最终仍须通过 M8 回归。M0~M9 的定义见第 4 节。 + +| 编号 | 功能与边界 | 完成阶段 | 关键验收 | +| --- | --- | --- | --- | +| F01 | `.nes` 导入,识别 iNES/NES 2.0 文件头;按测试清单声明兼容性 | M2 | 中文名、重复内容、同名不同内容、损坏文件均正确处理 | +| F02 | 游戏列表、搜索、收藏、最近游玩、从列表移除 | M6 | 元数据持久化;移除列表项不误删存档 | +| F03 | 启动、暂停、继续、重置、退出、再次加载 | M2 | 操作顺序完整;失败后仍能回到列表 | +| F04 | 横屏、保持比例、整数缩放、最近邻/线性过滤 | M2 基础,M6 完成 | 画面不拉伸,设置切换和 Surface 重建正常 | +| F05 | 声音、音量、静音、音画同步、音频设备变化 | M3 | 速度正确,无持续爆音或累积性偏移 | +| F06 | X5 Lite 和标准 Android 手柄,默认映射、自定义绑定、A/B 交换 | M4 | 组合输入、多来源输入和配置恢复正确 | +| F07 | 死区、方向冲突处理、A/B 连发、暂停快捷键、手柄导航 | M4;存档导航在 M5 联验 | 不残留按键,主要操作可仅靠手柄完成 | +| F08 | RB 按住快进,可关闭;来自设计文档默认映射 | M3 引擎,M4 绑定 | 松开、暂停或断开后恢复正常速度和声音 | +| F09 | 游戏自身存档、10 个手动即时存档槽、最近 3 份自动恢复点 | M2 基础,M5 完成 | 数据分 ROM 隔离,失败不破坏有效版本 | +| F10 | 存档导入导出、校验、备份、版本检查和失败恢复 | M5 | 导出后可重新导入;默认不包含 ROM | +| F11 | 后台/锁屏暂停、返回导航、界面重建、断柄和异常启动恢复 | M2 基础,M7 完成 | 无后台声音、持续黑屏、输入卡住或崩溃循环 | +| F12 | 虚拟方向键、A/B、Start、Select,基础触屏菜单操作 | M6 | 无手柄可完成基本游戏操作,支持多点触控和取消事件 | +| F13 | 手柄测试、运行状态、错误日志和诊断导出 | M1 基础,M7 完成 | 能定位设备、输入、音频、存档和原生错误 | +| F14 | arm64 发布、4 KB/16 KB 验证、安装升级、源码及许可证交付 | M8~M9 | 发布包、源码、符号、构建记录和验收报告对应 | + +### 1.3 明确不做 + +V1.0 不做联网对战、云存档、多平台模拟、在线下载游戏、复杂 CRT 滤镜、回溯、run-ahead、用户下载或切换内核。FDS、光枪、四人适配器和第二只手柄的完整体验留待 V1.1 之后。 + +导入器首版仅开放 `.nes`,不扩展到压缩包、UNIF 或固件管理。应用不附带商业游戏 ROM。首版交付以可安装 APK 为准,应用商店上架不计入本轮工期。 + +## 2. 技术基线与实施决策 + +### 2.1 工程基线 + +| 项目 | 计划选择 | 落地要求 | +| --- | --- | --- | +| Android | `minSdk 28`,`compileSdk 36`,`targetSdk 36` | 延续设计目标;实际手机 API、ABI 和页大小在 M1 读取 | +| 应用层 | Kotlin、AndroidX、原生 View | 单一 `app` 模块,按包划分职责;游戏使用独立页面 | +| 数据 | Room+DataStore | Room 管理游戏元数据;DataStore 管理设置和控制器配置 | +| 内核 | FCEUmm+libretro 接口 | M0 选定完整提交 SHA;M2 编译验证后冻结 | +| 原生层 | C/C++、JNI、Android NDK、CMake | 优先将固定内核静态链接进 JNI 库;上游构建适配保留可复现脚本 | +| 视频 | `GLSurfaceView`+OpenGL ES | 原生帧缓冲交接;不经 Kotlin 每帧搬运图像 | +| 音频 | Oboe | 记录实际流参数,支持请求低延迟失败后的回退 | +| 构建工具 | AGP 8.13.2、Gradle 8.13、JDK 17 | 采用设计给出的兼容组合;M0 在本机完成构建验证 | +| NDK | r28 或更新的稳定版本 | M0 锁定精确版本,不在配置中保留“r28+”或动态版本 | +| ABI | 发布 `arm64-v8a`,测试按需增加 `x86_64` | 测试 ABI 通过不能替代 arm64 发布包的验证 | +| 版本管理 | Git、Gradle Wrapper、依赖版本目录 | 固定 Kotlin、AndroidX、Room、DataStore、Oboe、CMake 等实际版本 | + +AGP、Gradle 和 JDK 组合参照 [Android 官方 AGP 8.13 兼容说明](https://developer.android.com/build/releases/agp-8-13-0-release-notes)。本计划不将这些版本称为“最新”;实际依赖锁定及构建成功记录属于 M0 交付物。 + +NDK r28 起默认采用 16 KB 对齐,但仍需检查全部原生依赖、ELF、APK 打包与运行时行为,并在 16 KB 环境运行。检查依据为 [Android 官方 16 KB 适配指南](https://developer.android.com/guide/practices/page-sizes)。 + +### 2.2 本计划补充的默认行为 + +| 决策 | 默认方案 | 确认节点 | +| --- | --- | --- | +| 产品身份 | 显示名称固定为 NESLite;正式 `applicationId` 和签名延续策略在首个长期保留数据的 APK 前确定 | M0 | +| 模拟会话 | 同一时间仅一个 ROM、一个内核实例、一个玩家端口 | M2 | +| 区域时序 | 默认由内核判断,执行频率和采样率读取内核 AV 信息 | M2~M3 | +| 显示 | 默认 4:3 保持比例、最近邻;另设原始像素整数缩放模式 | M2,M6 提供设置 | +| 基础游戏存档 | M2 即接通读取和正常暂停/退出写入,避免原型阶段完全不保存游戏进度 | M2 | +| 快进 | 提供可关闭的按住 2 倍速,期间静音;退出时清空旧音频并重新建立时钟基线 | M3;性能实测后冻结 | +| 自动保存 | 建议变化的游戏存档每 10 秒提交一次,自动即时恢复点每 60 秒生成一次;暂停/退出额外请求提交 | M5 按实测开销冻结 | +| 恢复 | 回到前台、重新接入手柄或发现异常会话时,先处于暂停/恢复选择状态,由用户继续 | M2 基础,M7 完成 | +| 从列表移除 | 默认隐藏游戏条目并保留存档;再次导入同哈希内容时恢复关联 | M6 | +| 工程规模 | 先完成单模块应用,不提前拆分多工程或建设插件平台 | M0 | + +2 倍快进是本计划提出的目标,并非性能承诺;若实测不能稳定达到,需调整默认倍率并同步验收清单。存档周期也必须通过帧时间测试后确定。已成功提交的存档应保持有效,突然终止可能丢失最近一次提交之后的进度。 + +## 3. 架构与模块契约 + +### 3.1 模块职责 + +| 模块 | 主要职责 | 边界 | +| --- | --- | --- | +| `ui` | 游戏库、游戏页、暂停菜单、设置、存档和诊断页面 | 展示状态、提交命令,不直接调用内核 | +| `session` | 会话状态、Activity/Surface 绑定、音频焦点及恢复协调 | 不长期持有已销毁的 Activity 或 View | +| `input` | 设备监听、映射、死区、多来源状态合成、菜单导航 | 输出玩家一的按钮快照和单次菜单动作 | +| `storage` | SAF 导入导出、内部 ROM、Room 索引、数据迁移 | 不把 `content://` URI 作为原生文件路径 | +| `jni` | 命令、输入快照、状态和错误通知 | 控制消息低频传递;视频和音频留在原生层 | +| `core_host` | libretro 生命周期、环境回调、内核配置和能力协商 | 不支持的请求返回失败并记录;必要能力缺失时停止加载 | +| `engine` | 模拟线程、命令队列、运行时钟、快进和诊断计数 | 独占内核调用,控制队列有界 | +| `video` | 像素转换、帧缓冲、GL 纹理、比例与过滤 | 处理宽高、`pitch` 和缓冲所有权 | +| `audio` | Oboe 流、重采样、环形缓冲、设备重建和水位 | 回调只消费预分配数据,不等待内核 | +| `state` | 存档快照、元数据、校验、原子提交、备份和恢复 | 模拟线程采集,文件线程提交,成功落盘后才通知“保存成功” | +| `diagnostics` | 版本、设备、输入、帧率、缓冲、错误和导出 | 日志限额轮换,默认不导出 ROM 内容 | + +环境回调的语义与初始化流程依据 [libretro 官方接口说明](https://docs.libretro.com/development/cores/developing-cores/);M2 需对照锁定版本实际使用的请求形成支持清单,而不是把所有请求都返回成功。 + +### 3.2 线程所有权 + +1. **Android 主线程**处理 UI、输入事件和生命周期,只提交异步命令,不等待模拟线程或文件写入。 +2. **模拟线程**串行调用初始化、加载、`retro_run()`、重置、状态序列化、反序列化、卸载和销毁;图像和音频在回调中复制到宿主缓冲,存档内存在保存采集点复制为不可变快照,避免其他线程使用内核临时指针或正在变化的内存。 +3. **GL 线程**只显示最近可用的完整帧。过时画面可以丢弃,但不能因此跳过正常模式下应执行的模拟帧。 +4. **音频回调线程**只消费环形缓冲,数据不足时补静音并计数;不做文件 I/O、动态分配、睡眠或等待互斥锁。此约束参照 [Oboe 低延迟音频指南](https://developer.android.com/games/sdk/oboe/low-latency-audio)。 +5. **文件工作线程**处理不可变快照和导入导出;每个 ROM 的存档写入按序提交,旧任务不得覆盖新任务。 + +视频采用预分配的双缓冲或三缓冲,交接时明确读写所有权;音频采用有界环形缓冲。重采样和水位控制在非音频回调线程完成。所有队列、日志和历史统计都有容量上限。 + +### 3.3 会话状态与命令 + +```text +Idle → Loading → Paused → Running + ↑ ↓ + └─ Pausing +Paused → Stopping → Idle +加载或运行失败 → Error → 安全清理 → Idle +``` + +- `Load / Pause / Resume / Reset / Save / LoadState / Stop` 均通过命令队列处理,返回完成或失败结果;输入快照独立更新。 +- 加载成功后仅在前台、Surface 可用且资源就绪时首次自动运行;后台恢复和断柄恢复需要用户继续。 +- 暂停菜单、失焦、锁屏、断柄及 Surface 丢失先触发暂停和输入清理;音频及时静音。M5 起再纳入完整恢复点提交。 +- `Reset`、存档和读档在帧边界执行;读档期间暂停推进,成功或回滚后清空音频、废弃旧待显示帧并重建时间基线。 +- 使用会话编号标记异步工作;已经退出的游戏不能被迟到的加载、音频重建或保存通知重新激活。 +- Activity 重建只重新连接会话与显示资源,不创建第二个模拟线程;进程重建则从磁盘记录恢复选择,不依赖旧对象。 + +### 3.4 持久化约定 + +```text +应用内部 files/ +├── roms/.nes +├── saves//battery/ 游戏自身存档及有效备份 +├── saves//states/ 10 个手动槽位及元数据、缩略图 +├── saves//auto/ 最近 3 份自动恢复点 +├── system/ 内核需要的稳定系统目录 +└── diagnostics/ 限额日志及会话标记 +``` + +Room 数据库和 DataStore 使用各自标准应用目录;数据库记录游戏哈希、显示名、内部文件关联、收藏、最近游玩时间和列表可见状态。哈希按导入文件的完整字节计算,不擅自去头或改写文件;内容不同的版本分别管理。 + +导入按“读取 URI → 有界流式复制和头部校验 → 计算 SHA-256 → 提交内部正式文件 → 数据库事务登记”执行。取消、空间不足及提交中断必须清理临时文件;数据库和文件系统不能形成单一事务,因此需在启动时对未登记正式文件及缺失文件记录进行核对和恢复。 + +存档采用“不可变快照 → 同目录临时文件 → 写入并刷新 → 校验 → 原子替换 → 备份轮换”的提交流程。为电池存档与即时存档分别定义格式和兼容检查;即时存档记录 ROM 哈希、内核名称/提交、封装版本、相关配置、时间、长度和校验值。导入的存档包检查路径、条目大小和总大小,不能写出目标存档目录。 + +## 4. 里程碑、依赖与工期 + +### 4.1 估算前提 + +按 **1 名熟悉 Kotlin 和 C/C++ 的开发者全职实施、每周 5 个工作日**估算。开发者承担代码、构建、自动测试和报告整理;设备持有人协助 X5 Lite、MagicOS 10 和实际游玩验收。两种角色可由同一人承担。 + +基础工作量约 **56~73 人日**,加约 20% 联调和缺陷修复缓冲后约 **67~88 人日,日历约 14~18 周**。此范围不是交付承诺,不包含设备等待、首次学习 Android/NDK 或额外上架工作。兼职按有效投入折算;M1 和 M3 结束后重新估算。 + +| 阶段 | 应用版本 | 主要目标 | 依赖 | 工作量 | 阶段产物 | +| --- | --- | --- | --- | --- | --- | +| M0 | 工程准备 | 需求、构建、版本、测试资源基线 | 无 | 3~4 人日 | 最小工程、构建记录、锁定清单 | +| M1 | 0.1.x | 原生库与真实手柄诊断 | M0 | 5~7 人日 | 诊断 APK、设备 JSON、键位表 | +| M2 | 0.2.x | 内核、导入、画面和基础操作 | M1 | 7~9 人日 | 无完整音频的运行原型、基础电池存档 | +| M3 | 0.3.x | 正确速度、连续声音和音画同步 | M2 | 8~10 人日 | 首个音画完整可玩版本、性能基线 | +| M4 | 0.4.x | 手柄映射、连发、导航和快捷操作 | M3 | 5~6 人日 | 手柄体验版本、输入回归记录 | +| M5 | 0.5.x | 完整存档、备份、导入导出和恢复 | M3、M4 | 8~10 人日 | 可靠存档版本、格式与故障报告 | +| M6 | 0.6.x | 游戏库、设置、存档 UI 和虚拟按键 | M4、M5 | 6~8 人日 | 日常使用 Beta | +| M7 | 0.7.x | MagicOS 10 和系统行为专项适配 | M6 | 4~6 人日 | 系统兼容报告 | +| M8 | 0.9.x | 全量回归、性能、升级与发布准备 | M1~M7 通过 | 8~10 人日 | 候选发布版 RC | +| M9 | 1.0.0 | 发布验收和归档 | M8 通过 | 2~3 人日 | 正式 APK、对应源码和交付包 | + +版本顺序沿用设计文档,0.8.x 不安排独立范围。M0 无需产品级 APK;M1 起每个里程碑必须有可安装 APK、源码提交、构建说明、验收记录和已知问题。 + +关键路径为 **工程与实机输入 → 内核与画面 → 音频和时钟 → 手柄体验与存档 → 完整界面 → 系统适配 → 回归发布**。不得用后续界面完成度替代前序正确性验收。设备暂不可用时可推进不依赖实机的开发和自动测试,但对应实机门槛仍记为“未验证”。 + +### 4.2 阶段状态规则 + +所有下列任务初始状态为“未开始”。跟踪时使用“未开始/进行中/待实机/通过/失败”,不能把待实机标成完成。关键数据损坏、速度错误、崩溃或输入残留未解决时,该阶段不通过。 + +## 5. 分阶段执行任务 + +### M0:建立可重复的工程基线 + +| 任务 | 工作内容 | +| --- | --- | +| M0-01 | 初始化 Git、单 `app` Android 工程、Gradle Wrapper、CMake 和 JNI 空入口;确定应用 ID 与版本命名 | +| M0-02 | 核对本机 JDK/SDK/NDK/CMake,锁定工具及依赖精确版本,记录安装和构建步骤 | +| M0-03 | 选择 FCEUmm 提交,登记 libretro 头文件和 Oboe 来源;统一采用固定提交的依赖引入方式,登记本地补丁 | +| M0-04 | 建立测试 ROM 清单、设备表和验收模板,整理依赖许可证;建立本地构建、检查和测试入口 | + +**出口条件:** 从干净检出能按文档生成调试 APK;没有依赖手动复制的未知原生库;代码、依赖和构建版本可追溯。记录未齐备的实机与测试资源,提供取得方法。 + +### M1/0.1.x:设备与 X5 Lite 诊断 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.1.0/M1-01 | 安装启动、JNI 自检;读取机型、系统 API、ABI、页大小、刷新率和屏幕信息 | +| 0.1.1/M1-02 | 枚举设备名称、描述符、厂商/产品标识、输入源、轴范围和设备连接变化 | +| 0.1.2/M1-03 | 实时展示按钮按下/松开、HAT、摇杆、扳机;保存用于复现的输入事件序列 | +| 0.1.3/M1-04 | 失焦与热插拔状态清理、设备 JSON 导出、X5 Lite 实测键位表和模式说明 | + +**出口条件:** 目标手机正常加载原生库;方向+A/B 同时按下可观察;全部松开后状态归零;拔出后无残留、重连后可继续检测。真实按键码来自实测,不由按键字母推断。 + +按设计使用 X5 Lite 原生安卓模式,核对随设备说明及实际表现;测试前关闭硬件连发。保留厂商模式切换组合,不占用“视图+菜单长按”。本阶段不要求加载 ROM。 + +### M2/0.2.x:打通内核运行链路 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.2.0/M2-01 | 编译锁定的 FCEUmm;接入 libretro API 版本检查、回调注册、初始化、目录、选项、玩家一端口和卸载 | +| 0.2.1/M2-02 | SAF 导入、文件大小与头部校验、SHA-256 去重、稳定内部副本、最小 Room 索引和错误提示 | +| 0.2.2/M2-03 | 视频回调、协商像素格式、行跨度与重复帧处理;GL 显示、4:3 和整数缩放基础能力 | +| 0.2.3/M2-04 | 模拟线程和会话状态机;手柄快照接入;启动、暂停、继续、重置、退出;基础电池存档读写 | + +**出口条件:** 至少 3 个有权使用的样本完成加载和运行,其中包含一个电池存档样本;完整操作流程通过;正常退出再加载后游戏自身进度可恢复;损坏文件加载失败不会破坏现有数据。 + +音频回调在本阶段按接口正确接收并消费数据,暂不输出声音;无音频时按内核时序与单调时钟执行,不能无节制调用 `retro_run()`。后台和 Surface 丢失的基础暂停逻辑同时接入。高级备份与故障保证在 M5 验收前仍标为未完成。 + +### M3/0.3.x:声音与正确运行速度 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.3.0/M3-01 | Oboe 输出、预分配环形缓冲、欠载补静音与统计;低延迟流失败后按能力回退 | +| 0.3.1/M3-02 | 读取内核与设备采样率,完成重采样、声道/格式适配,记录实际流参数 | +| 0.3.2/M3-03 | 以单调时钟、内核时序及音频消费/水位进行调度;显示节奏独立;缓冲有界且不无限追帧 | +| 0.3.3/M3-04 | 音量、静音、音频焦点、设备重建;音频不可用的时钟回退;快进及回到正常速度 | + +**出口条件:** NTSC 与 PAL 样本各连续运行至少 30 分钟;按第 7 节方法验证速度和音频缓冲;暂停后无旧声音继续播放,恢复和设备切换后不累积延迟。快进松开后正常速度恢复,断柄或失焦取消快进。 + +内核帧率和采样率从返回信息读取;[FCEUmm 官方文档](https://docs.libretro.com/library/fceumm/)给出的 NTSC、PAL/Dendy 时序用于准备测试,不能替代运行时读取。静音时保留正常调度;音频流关闭时显式切换至单调时钟,避免因无音频消费而挂起或加速。 + +### M4/0.4.x:完成手柄操作体验 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.4.0/M4-01 | 将 M1 实测档案转为默认映射;加入 A/B 交换、自定义绑定、恢复默认和冲突提示 | +| 0.4.1/M4-02 | 按来源维护状态;处理 HAT/按键重复上报、轴阈值滞回、死区和相反方向归零 | +| 0.4.2/M4-03 | A/B 软件连发、暂停菜单、RB 快进绑定;快捷动作按边沿触发,快速读档默认不绑定易误触单键 | +| 0.4.3/M4-04 | 最小游戏列表与菜单的手柄焦点导航、配置持久化、重连后的档案匹配 | + +**默认映射:** 十字键为方向,左摇杆可选方向;A/B 对应 NES A/B;X/Y 对应 A/B 连发;菜单键为 Start、视图键为 Select;右摇杆按下打开/关闭暂停菜单;RB 按住快进。实际键码以 M1 记录为准,系统返回和触屏暂停入口始终可用。 + +**出口条件:** 组合输入、重复轴/按钮事件和失焦清理通过自动回放;20 轮插拔后无残留;仅靠手柄可进入游戏、暂停、继续、重置和退出。存档选择与读档导航依赖 M5,在 M5 完成后补做完整验收,不能在 M4 宣称已通过。 + +连发周期按模拟时间生成,不能随手机刷新率变化;手柄硬件连发与软件连发分别测试,默认验证时关闭硬件连发。 + +### M5/0.5.x:可靠存档和恢复 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.5.0/M5-01 | 完善电池存档变化检测、周期提交、暂停/退出提交、按 ROM 隔离、原子替换和有效备份 | +| 0.5.1/M5-02 | 10 个手动即时存档槽、时间、缩略图、校验元数据;存读档在模拟线程安全点执行 | +| 0.5.2/M5-03 | 自动恢复点保留最近 3 份,失败不挤掉有效副本;异常会话标记和恢复选择入口 | +| 0.5.3/M5-04 | SAF 存档包导入导出、版本与配置检查、读档前备份、失败回滚、空间不足和中断恢复 | + +**出口条件:** 同一锁定内核下 100 次存读档循环通过;损坏、截断、错误哈希、空间不足和写入中终止均不破坏此前有效提交;存档包导出后重新导入可恢复;仅靠手柄完成选择槽位、存档、读档和退出。 + +反序列化失败视为内核状态可能已改变:优先恢复读档前快照,回滚失败则安全卸载并重新加载游戏,使用已提交的有效电池存档。不能继续运行未知状态。不同内核提交的即时存档默认拒绝自动恢复,保留原文件并说明原因;跨版本兼容需独立验证。 + +### M6/0.6.x:完整日常界面 + +| 版本/任务 | 工作内容 | +| --- | --- | +| 0.6.0/M6-01 | 完善游戏库、搜索、收藏、最近游玩、隐藏列表项和再次导入恢复关联 | +| 0.6.1/M6-02 | 显示比例、缩放、过滤、音量、静音、输入和快进开关;设置持久化 | +| 0.6.2/M6-03 | 存档管理、游戏信息、可理解的错误提示、保存状态和失败重试入口 | +| 0.6.3/M6-04 | 虚拟方向键、A/B、Start、Select、多点触控;首次使用引导和无手柄流程 | + +**出口条件:** 首次安装后从导入到保存退出的流程完整;全手柄和纯触屏两条路径均可使用;触屏与手柄同时输入时,松开一个来源不会释放另一个来源仍按住的键。所有页面覆盖空列表、加载中、失败、无手柄和长中文文件名状态。 + +### M7/0.7.x:MagicOS 10 专项适配 + +| 任务 | 工作内容 | +| --- | --- | +| M7-01 | 采用 AndroidX 返回处理;游戏返回打开暂停菜单、菜单返回继续、设置返回上级、列表返回退出 | +| M7-02 | 横屏安全区域、挖孔、系统栏、手势边缘及目标设备提供的刷新率模式验证 | +| M7-03 | 后台、锁屏、通知/来电导致的焦点变化、音频路由变化、Surface 和 Activity 重建联调 | +| M7-04 | 进程重建、异常会话恢复、重复崩溃保护;完善状态展示、日志轮换和诊断导出 | + +**出口条件:** 20 轮后台/恢复及 20 轮锁屏/解锁后无黑屏、后台声音和卡键;Surface 重建不重复创建内核;同一异常 ROM/状态不会导致启动循环。回前台先恢复资源,再由用户继续。无需关闭系统全部省电策略,不引入后台持续模拟服务。 + +### M8/0.9.x:发布候选版 + +| 任务 | 工作内容 | +| --- | --- | +| M8-01 | 冻结功能、依赖和内核版本,完成全部兼容样本、输入、音频、系统及存档回归 | +| M8-02 | 代表游戏长时间运行;收集速度、帧时间、内存、音频欠载和输入延迟,修复崩溃及 ANR | +| M8-03 | 检查全部发布原生库与 APK 的 16 KB 对齐;4 KB 和 16 KB 环境运行;API 28 基线冒烟 | +| M8-04 | 同应用 ID/签名覆盖升级、Room/设置迁移和存档兼容验证;整理发布源码、许可证、符号和已知问题 | + +**出口条件:** 第 7 节发布门槛全部通过,无阻断或高优先级缺陷;最终候选包而非仅调试包通过安装、加载、输入、音频、保存恢复及退出冒烟。修复后重跑受影响用例;内核、时钟或存档格式变动须重跑对应完整测试集。 + +### M9/1.0.0:正式交付 + +| 任务 | 工作内容 | +| --- | --- | +| M9-01 | 核对范围、验收报告与已知问题,确定版本号和递增 `versionCode`,建立发布源码标记 | +| M9-02 | 生成签名 APK、校验和、源码包、依赖与补丁清单、原生符号和使用说明 | +| M9-03 | 对正式交付 APK 做最后冒烟,归档构建环境、验收记录及后续问题清单 | + +**出口条件:** 用户可安装并在规定测试范围内完成完整使用流程;产物可以追溯至同一源码版本。签名密钥安全保管,不放入仓库或交付源码包。 + +## 6. 文档、目录与日常交付 + +建议延续设计中的单应用目录: + +```text +NESLite/ +├── design.md +├── app/src/main/ +│ ├── java//{ui,session,input,storage,diagnostics}/ +│ ├── cpp/{jni,core_host,engine,video,audio,state}/ +│ └── res/ +├── app/src/test/ Kotlin 纯逻辑测试 +├── app/src/androidTest/ Android 集成测试 +├── third_party/{fceumm,libretro,oboe}/ +├── tests/{native,input,state,compatibility,lifecycle}/ +├── scripts/ 构建、测试、对齐检查和诊断整理 +├── docs/ +│ ├── development_plan_V1.0.md +│ ├── requirements.md +│ ├── architecture.md +│ ├── build.md +│ ├── controller-x5lite.md +│ ├── save-format.md +│ ├── acceptance.md +│ └── reports/ +├── THIRD_PARTY_NOTICES +└── LICENSE +``` + +此处为待建立的结构,不表示这些文件已存在。M0 建立需求/构建文档,M1 完成设备档案,M2 完成架构和内核支持清单,M5 完成存档格式,M8 汇总验收和发布说明。原生测试需接入独立测试构建;仅放入 `tests/` 不等于已经执行。 + +每个任务按“实现 → 自动验证 → 必要实机验证 → 更新文档/已知问题 → 提交”完成。M0 建立可本地执行的统一检查入口;如之后配置远程 CI,复用相同入口,不另设只在远程存在的步骤。 + +每份阶段报告至少记录:应用版本、源码提交、内核提交、设备与系统、ABI/页大小/刷新率、ROM 哈希、配置、测试步骤、预期、实际结果、日志位置及未通过项。尚未执行的测试明确标记“未验证”。 + +## 7. 测试策略与量化验收 + +### 7.1 环境与样本 + +| 测试环境 | 用途 | 限制 | +| --- | --- | --- | +| 目标 MagicOS 10 手机+X5 Lite | 输入、音频、性能、插拔、系统适配的主验收 | 记录真实机型和参数;不由系统名称推断硬件 | +| API 28 的可用测试设备或模拟器 | 最低系统版本的安装、导入、运行和保存冒烟 | 不替代目标手机的性能与手柄测试 | +| 4 KB 与 16 KB 的适配环境 | 原生加载、游戏运行、音频和保存恢复 | 记录实际 ABI;x86_64 的通过不能替代 arm64 原生库检查 | +| 目标手机支持的各刷新率、可用音频路由 | 速度独立性、显示和设备切换 | 没有的硬件条件记录为未覆盖,不虚构结果 | + +M0 建立版本化 ROM 清单,只使用自制或有权使用的样本。M2 至少 3 个样本;M8 建议不少于 12 个,覆盖 Mapper 0/1/2/3/4、NTSC/PAL、电池存档,以及 iNES 和 NES 2.0 文件头;多个维度可以由同一 ROM 覆盖。Dendy 时序和更多 Mapper 在有合适样本时扩展,未覆盖项明确记录。 + +清单记录来源与使用/再分发条件、SHA-256、Mapper、区域、存档类型、预期表现及结果。功能测试 ROM 有自检结果时以其结果验收;游戏样本使用固定操作步骤与观察点。不以“能显示标题画面”认定完整兼容。 + +### 7.2 自动测试与人工测试分工 + +| 层次 | 必须覆盖的行为 | +| --- | --- | +| Kotlin 单元测试 | 输入状态合成、方向冲突、死区滞回、去重、映射持久化、会话转换和文件头校验 | +| 原生单元/集成测试 | 有界缓冲、重采样连续性、时钟和快进切换、命令次序、序列化失败回滚 | +| Android 集成测试 | SAF 导入/导出、Room 事务与升级、生命周期、Surface 重建、虚拟按键取消事件 | +| 故障注入 | 截断、错误校验和、错误 ROM/内核版本、写盘不足、提交中终止、重复异步命令 | +| 实机人工验收 | X5 Lite 组合输入与热插拔、手柄焦点导航、听感、系统返回、安全区域、长时间游玩 | + +文件写入故障通过可替换的文件接口或测试环境注入;不以填满用户手机全部空间作为常规测试方法。写盘中断测试覆盖临时写入、替换前和替换后等边界,并区分已提交与尚未提交数据。 + +### 7.3 V1.0 发布指标 + +以下为目标,均须保存测量记录。增加的测量窗口和采样方法用于使设计中的指标可执行;如需调整,在 M3/M5 实测后更新计划和验收文档,不在发布时临时放宽以掩盖失败。 + +| 指标 | 目标 | 测量方法 | +| --- | --- | --- | +| 正常模拟速度 | 99.5%~100.5% | NTSC、PAL 各运行至少 30 分钟;计算已执行模拟时间/有效单调时钟时间;检查每个连续 60 秒窗口和全程均值,排除暂停、加载、快进 | +| 长时稳定性 | 代表性样本各 2 小时,无崩溃、ANR、持续内存增长 | 至少选动作/滚屏与电池存档两类;每分钟采集 Java/native 内存与 PSS,检查预热后趋势及往返操作是否泄漏 | +| 输入可靠性 | 组合序列和清理场景无残留、无重复菜单动作 | 自动回放和实机组合输入;统计异常,必须为 0 | +| 软件输入延迟 | 正常负载 P95 不超过 1 个实际模拟帧 | 同一单调时间域记录 Android 事件接收至首次内核采样,目标机采样至少 1,000 次,排除暂停/绑定界面 | +| 存档可靠性 | 100 次存读档全部通过,故障不破坏已提交有效版本 | 比较固定测试状态、游戏进度与校验值;覆盖手动槽、自动轮换、电池存档和导入导出 | +| 手柄热插拔 | 20 轮断开/重连通过 | 方向及 A/B 按住时拔出,检查暂停、清理、配置匹配和重新操作 | +| 后台与锁屏恢复 | 后台 20 轮、锁屏 20 轮通过 | 检查无后台声音、无黑屏/卡键,用户继续后运行正常 | +| 音频稳定性 | 无持续爆音、旧音频积压或累积性音画偏移 | NTSC/PAL 各 30 分钟听感与水位记录;流预热后正常前台段目标欠载为 0,切换段单独统计并确认恢复 | +| 4 KB/16 KB | 原生加载和基本运行通过 | 记录页大小;逐库 ELF 与 APK 对齐检查,并执行运行、声音和保存恢复 | +| 安装升级 | 新装及同签名覆盖升级通过 | 保留至少一个旧测试版本的数据集,验证 ROM 关联、收藏、设置、游戏存档及状态兼容处理 | + +软件输入延迟只覆盖“应用收到事件 → 内核采样”,不能作为按键到屏幕总延迟。音频环形缓冲水位也不能代表全部端到端延迟;如报告端到端指标,另附实测方法与证据。 + +### 7.4 缺陷分级与放行 + +- **阻断:** 无法安装/启动/运行,已提交存档损坏或串档,启动崩溃循环。必须修复。 +- **高优先级:** 可复现崩溃或 ANR、速度错误、后台发声、持续黑屏、卡键、主要手柄操作中断。必须修复。 +- **一般:** 不影响核心流程的显示或提示问题,以及测试范围外个别 ROM 的兼容问题。记录复现、影响和绕行方法后逐项决定是否放行。 + +只对已列明并通过测试的范围声明兼容;不能把规定测试集中的失败通过更改名称或删除记录视作通过。范围调整需同步设计依据、计划及已知问题。 + +## 8. 风险与处理安排 + +| 风险 | 最早检查 | 处理方式 | +| --- | --- | --- | +| 实际手机环境或 X5 Lite 键码与设想不同 | M1 | 输出设备和输入档案;以实际事件建立默认映射,保留通用配置 | +| FCEUmm 构建或宿主接口遗漏 | M0~M2 | 固定提交;维护环境请求清单和最小加载测试,局部补丁单独记录 | +| 音频时钟、重采样或缓冲导致变速/延迟累积 | M3 | 先测时序与水位,再调整缓冲;保留音频不可用的时钟回退 | +| Surface、音频流重建与退出发生竞态 | M2~M7 | 单内核线程、会话编号和状态检查,重复调用及迟到结果测试 | +| 存档写入中断或读档失败破坏进度 | M2 基础,M5 完整 | 快照隔离、原子提交、有效备份、故障注入和失败回滚 | +| 内核升级使即时存档失效 | M5/M8 | V1.0 冻结内核;元数据校验、保留旧文件,升级前做兼容测试 | +| 16 KB 检查只覆盖自研库而漏掉依赖 | M0、M8 | 清点最终 APK 内每个原生库,检查对齐并在实际 16 KB 环境运行 | +| 实机或合法测试 ROM 不齐 | M0 | 早建缺口清单;可继续独立开发,但不跳过对应验收 | +| UI 或附加功能挤占可靠性工作 | 全程 | 优先内核、时钟、输入和存档;本轮不加入范围外功能 | +| 源码与发布包、许可证不对应 | M0、M8~M9 | 固定来源,保存补丁/构建选项和符号,发布时逐项核对 | + +FCEUmm 上游声明采用 GNU GPL v2,并要求参考源文件头部细节,见 [FCEUmm 上游仓库](https://github.com/libretro/libretro-fceumm)。按设计采用 GPL 兼容的源码交付方案;M0 核对选定提交及全部依赖条款,M8 准备与 APK 对应的完整源码、构建说明、版权和许可证材料。libretro 头文件的许可证不能替代所链接内核的许可证。 + +## 9. 最终交付清单 + +- [ ] 签名 `NESLite-1.0.0-arm64-v8a.apk` 及 SHA-256 校验和。 +- [ ] 对应源码版本/源码包、锁定依赖、FCEUmm 提交、构建选项和本地补丁。 +- [ ] 从干净环境构建的说明、精确工具链版本、原生符号与必要的混淆映射文件。 +- [ ] 快速使用说明:游戏导入、手柄模式/映射、暂停、存档、导出和恢复。 +- [ ] 设备与 ROM 兼容清单、自动和实机测试报告、性能及 16 KB 检查结果。 +- [ ] 存档格式、内核升级兼容策略、升级安装记录和已知问题。 +- [ ] `LICENSE`、`THIRD_PARTY_NOTICES` 及对应依赖许可证材料。 + +只有 F01~F14 在约定范围内完成、发布指标通过且无阻断/高优先级缺陷时,才将应用标记为 1.0.0。 + +## 10. 首轮启动清单 + +首轮执行 M0 和 M1,先交付能安装、能加载原生库、能验证真实手柄输入的 0.1.x 诊断版。 + +1. 建立 Android+JNI 最小工程,锁定工具链,生成首个可安装 APK。 +2. 确定应用 ID、依赖提交、基础数据目录及版本管理方式。 +3. 读取目标手机系统、ABI、页大小、屏幕和刷新率,导出设备信息。 +4. 接入 X5 Lite 设备枚举、按钮/轴展示、组合输入和松开状态。 +5. 验证失焦、拔出与重连,形成实测键位表与诊断报告。 +6. 完成 M1 出口检查后,进入 M2 的 ROM 导入和 FCEUmm 接入。 + +首轮以设备与手柄实测为目标。首次音画完整的可玩验收在 M3,可靠日常使用验收在 M6~M7,正式发布在 M8~M9 全部门槛通过后进行。 diff --git a/docs/identity.md b/docs/identity.md new file mode 100644 index 0000000..7890742 --- /dev/null +++ b/docs/identity.md @@ -0,0 +1,47 @@ +# 应用与数据身份 + +## 固定身份 + +| 项目 | 决定 | +| --- | --- | +| 显示名称 | `NESLite` | +| 正式 application ID/namespace | `org.neslite.app` | +| 当前开发版本 | `0.0.1-dev`,`versionCode = 1` | +| 调试 application ID | `org.neslite.app.debug` | +| 发布 ABI | `arm64-v8a` | +| min/target SDK | 28/36 | + +`org.neslite.app` 自 M0 起视为长期数据身份;在有用户数据的 APK 后不得改名。调试包采用独立 +ID,避免覆盖正式用户数据。 + +## 版本号规则 + +稳定版本的 `versionName` 为 `MAJOR.MINOR.PATCH`,`versionCode` 为 +`MAJOR × 1,000,000 + MINOR × 1,000 + PATCH`。例如 1.0.0 是 `1,000,000`,1.2.7 是 +`1,002,007`。发布前开发构建可使用较小、单调递增的编号和 `-dev` 后缀,但不能回退已安装 +发布包的 `versionCode`。 + +## 签名延续策略 + +调试 APK 使用 Android SDK 的 debug keystore,仅作开发验证。发布使用专用、离线保存的 +release keystore;私钥、口令、`*.jks`/`*.keystore` 和 CI 密钥不进入 Git、源码包或诊断导出。 +首次发布时记录别名、证书 SHA-256 指纹、有效期和保管责任人到未提交的发布保管记录。之后所有 +`org.neslite.app` 更新必须使用同一签名证书;若证书不可恢复,不能以同一 ID 声明无缝升级。 + +## 数据目录约定 + +应用内部 `files/` 的长期布局如下,正式 ROM 不放在 `cache/`: + +```text +files/ +├── roms/.nes +├── saves//battery/ +├── saves//states/ +├── saves//auto/ +├── system/ +└── diagnostics/ +``` + +Room 与 DataStore 使用 Android 标准私有目录。ROM 身份是导入文件完整字节的 SHA-256;同名但 +不同内容必须独立,重新导入相同哈希才重新关联既有存档。目录本身在 M2/M5 实现,本文件只固定 +数据兼容约定。 diff --git a/docs/reports/m0-baseline.md b/docs/reports/m0-baseline.md new file mode 100644 index 0000000..83bce1e --- /dev/null +++ b/docs/reports/m0-baseline.md @@ -0,0 +1,34 @@ +# M0 基线报告 + +- 日期:2026-09-12 +- 源码提交:待首次提交 +- 验收目标:G0 构建基线 + +## 结果 + +| 编号 | 结果 | 证据 | +| --- | --- | --- | +| M0-02a | 通过 | JDK 17、SDK 36.1、NDK r28c、CMake 3.22.1 和 Gradle 8.13 均已实际调用;Java/Kotlin target 均锁定为 17。 | +| M0-01a | 通过 | `app-debug.apk` 已生成;内含唯一原生库 `lib/arm64-v8a/libneslite_jni.so`。 | +| M0-01b | 通过 | `docs/identity.md` 与 `app/build.gradle.kts`;APK 包名、版本和 SDK 范围已核对。 | +| M0-03a | 通过 | 三个固定提交均由 `tools/fetch-third-party.ps1` 检出。 | +| M0-03b | 通过 | `LICENSE`、`THIRD_PARTY_NOTICES.md` 与 `docs/dependencies.md`。 | +| M0-02b | 通过 | `docs/build.md`;已由外部构建生成 APK。 | +| M0-04a | 通过(资源待后续补齐) | `docs/requirements.md` 与资源缺口登记。 | +| M0-04b | 通过 | `tools/check.ps1` 已修正为直接调用 CTest;原生 smoke 通过,构建和模块测试入口有界。 | + +## 未闭合项 + +1. G0 仍需从干净检出以修正后的 `tools/check.ps1 -Scope Stage` 完整重跑;当前自动化终端仍有独立的 Java NIO selector 限制,不能替代该步骤。 +2. G2 前必须补齐 `docs/requirements.md` 所列三份有权使用的 ROM 样本和实际属性。 +3. M1 前需取得目标手机和 X5 Lite 的真实诊断数据;不能以型号推测替代。 + +## 已执行的本机检查 + +| 检查 | 参数 | 结果 | +| --- | --- | --- | +| 原生主机 smoke | Android CMake 3.22.1;Visual Studio 2022;`ctest` | 1/1 通过。 | +| JNI 交叉编译 | NDK 28.2.13676358;API 28;`arm64-v8a` | 生成 `libneslite_jni.so`;ELF header 为 `ELF64` / `AArch64`。 | +| 上游来源 | `tools/fetch-third-party.ps1` | FCEUmm、libretro header、Oboe 均在 manifest 指定提交。 | +| 静态材料 | XML、JSON、Wrapper entry point、空白检查 | 通过。 | +| Gradle/APK | JDK 17 + Gradle 8.13 | 构建成功;`app-debug.apk` 为 7,313,565 bytes,SHA-256 为 `7026BCA4B45B2ACC77F7EEB20408B3B48BB73FE7AC012957187BAB15B3071547`。 | diff --git a/docs/reports/phase-report-template.md b/docs/reports/phase-report-template.md new file mode 100644 index 0000000..5659060 --- /dev/null +++ b/docs/reports/phase-report-template.md @@ -0,0 +1,25 @@ +# 阶段报告模板:Gx + +- 阶段/版本: +- 日期: +- 源码提交: +- 内核、依赖与构建配置锁: +- APK/校验值: +- 设备、系统、ABI、页大小: +- ROM 样本(名称代号、SHA-256、区域、Mapper、头类型、存档类型): + +## 执行项 + +| 编号(M/L/H) | 前提和参数 | 命令/步骤 | 结果 | 日志或材料位置 | +| --- | --- | --- | --- | +| | | | 通过/失败/待实机 | | + +## 指标和异常 + +记录适用的窗口、样本数、时长、失败路径、内存/速度/音频数据,以及未解释的统计异常。 + +## 已知问题与复测决定 + +| 问题 | 影响 | 处理决定 | 需要重跑的 L/H 项 | +| --- | --- | --- | --- | +| | | | | diff --git a/docs/reports/rom-inventory.md b/docs/reports/rom-inventory.md new file mode 100644 index 0000000..a1fe067 --- /dev/null +++ b/docs/reports/rom-inventory.md @@ -0,0 +1,10 @@ +# ROM 样本登记 + +不得在本仓库、诊断导出或报告中提交未经授权的 ROM 内容。仅登记下列不含 ROM 数据的元数据; +每项必须保留取得依据以供验收查阅。 + +| 代号 | 合法来源/许可记录 | SHA-256 | 区域 | Mapper | 头类型 | 电池存档 | 状态 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| R-NROM | 待提供 | 待提供 | 待提供 | 待提供 | 待提供 | 否/待确认 | 未取得 | +| R-MAPPER | 待提供 | 待提供 | 待提供 | 待提供 | 待提供 | 否/待确认 | 未取得 | +| R-BATTERY | 待提供 | 待提供 | 待提供 | 待提供 | 待提供 | 是/待确认 | 未取得 | diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..9a66716 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,47 @@ +# 需求、设备与测试资源表 + +本表将设计需求映射到唯一的实现和验收位置,不把规划当成已完成结果。 + +## F01~F14 映射 + +| 需求 | 功能摘要 | 实现位置 | 功能门槛 | +| --- | --- | --- | --- | +| F01 | `.nes` 导入与 iNES/NES 2.0 识别 | M2-02a~M2-02c | G2 | +| F02 | 游戏库、搜索、收藏、移除 | M2-02b、M6-01 | G6 | +| F03 | 会话启动、暂停、继续、重置、退出 | M2-01c、M2-04 | G2 | +| F04 | 比例、整数缩放与过滤 | M2-03、M6-02a | G6 | +| F05 | 音频与正确时序 | M3、M7 联调 | G3/G7 | +| F06 | X5 Lite 和标准手柄映射 | M1、M4-01、M4-04b | G4 | +| F07 | 输入去重、死区、连发和导航 | M4、M5 联验 | G4/G5 | +| F08 | RB 按住快进 | M3-04d、M4-03b、M6-02b | G4/G6 | +| F09 | 电池、手动和自动存档 | M2-04d、M5-01~M5-03 | G5 | +| F10 | 存档导入导出与失败恢复 | M5-04 | G5 | +| F11 | 生命周期和异常恢复 | M2、M3、M5、M7 | G7 | +| F12 | 虚拟按键 | M6-04 | G6 | +| F13 | 设备与运行诊断 | M1、M3、M7 | G7 | +| F14 | 原生兼容和交付 | M0、M8、M9 | G8/G9 | + +## 设备待测参数 + +| 项目 | 目标/已知条件 | M0 状态 | 取得方式 | 最迟节点 | +| --- | --- | --- | --- | --- | +| 主手机 | Honor MagicOS 10 手机 | 具体机型、API、ABI、页大小、刷新率未采集 | M1 诊断页读取并导出 JSON | G1 | +| 控制器 | 小鸡 X5 Lite | Android 模式、VID/PID、descriptor、键码、轴范围、硬件连发状态未采集 | M1 用真实设备录制;测试前关闭硬件连发 | G1 | +| 4 KB 环境 | Android 设备或模拟器 | 未取得 | M8 按 H-NATIVE 记录 ABI/页大小 | G8 | +| 16 KB 环境 | Android 设备 | 未取得 | M8 按 H-NATIVE 记录 ABI/页大小 | G8 | +| API 28 环境 | Android 9 设备或模拟器 | 未取得 | M8 执行安装、导入、运行、保存冒烟 | G8 | + +## M2 ROM 样本获取安排 + +本项目不随应用分发 ROM。每个样本必须是使用者有权使用的自有转储或明确允许再分发的 +homebrew/test ROM,登记完整文件 SHA-256,不以文件名推断内容。 + +| 代号 | 目标维度 | 区域/Mapper/头类型/存档 | 当前状态 | 取得办法与使用依据 | 最迟节点 | +| --- | --- | --- | --- | --- | --- | +| R-NROM | 基础加载、输入和视频 | NTSC;NROM;iNES 或 NES 2.0 | 未取得 | 选择许可证允许的 NES homebrew/test ROM,保存来源许可页和原文件哈希 | G2 | +| R-MAPPER | Mapper 和 PAL 路径 | PAL;目标 Mapper;iNES 或 NES 2.0 | 未取得 | 从有权使用的实体卡带自行转储,或选择明确许可的测试 ROM;登记区域和 Mapper | G2 | +| R-BATTERY | 电池存档恢复 | NTSC 或 PAL;带电池存档的 Mapper;iNES 或 NES 2.0 | 未取得 | 使用者提供有权使用的带电池存档卡带转储;记录不含 ROM 内容的哈希和存档行为 | G2 | + +资源缺口:三份 ROM、两种区域的实际哈希、Mapper、头版本及一份电池存档样本均未提供。 +负责人必须在 G2 前将合法来源、完整 SHA-256、区域、Mapper、头类型、是否有电池存档填入 +`docs/reports/rom-inventory.md`;未补齐时 G2 不得勾选。 diff --git a/docs/toolchain.md b/docs/toolchain.md new file mode 100644 index 0000000..5c1c52d --- /dev/null +++ b/docs/toolchain.md @@ -0,0 +1,40 @@ +# M0 工具链与依赖锁定 + +记录日期:2026-09-12。构建和依赖版本只使用下表中的精确值;工程配置不允许 +`latest`、`+` 或浮动范围。 + +## 本机构建环境 + +| 项目 | 锁定版本 | 本机位置/状态 | 说明 | +| --- | --- | --- | --- | +| PowerShell | 7.6.6 | 系统默认 `pwsh` | 仅用于运行构建入口;不影响 APK 字节码或原生 ABI。 | +| JDK | Temurin 17.0.17+10 | `E:\\Codex\\NESLite\\.toolchains\\jdk-17.0.17+10` | 供 Gradle/AGP 使用;系统默认 JDK 21 不用于本工程。 | +| Android SDK Platform | 36.1 | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\platforms\\android-36.1` | `compileSdk = 36`,AGP 8.13 可支持 API 36.1。 | +| Android Build Tools | 36.1.0 | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\build-tools\\36.1.0` | 由 AGP 选择,不固定使用系统 `37.0.0`。 | +| NDK | 28.2.13676358 (r28c) | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\ndk\\28.2.13676358` | `app/build.gradle.kts` 中锁定。 | +| Android CMake | 3.22.1 | `C:\\Users\\shenw_o246oq4\\AppData\\Local\\Android\\Sdk\\cmake\\3.22.1` | `app/build.gradle.kts` 中锁定;不使用系统 CMake 4.4.0-rc2。 | +| AGP | 8.13.2 | Gradle version catalog | 要求 Gradle 8.13 与 JDK 17。 | +| Gradle Wrapper | 8.13 | `gradle/wrapper/gradle-wrapper.properties` | 分发包 SHA-256 已锁定。 | +| Kotlin | 2.3.0 | Gradle version catalog | AGP 8.13.2 支持 Kotlin 2.3。 | + +`app/build.gradle.kts` 同时将 Android Java source/target compatibility 和 Kotlin JVM toolchain 固定为 17, +避免 Gradle 运行时 JDK 影响 Kotlin/Java 目标版本的一致性。 + +SDK 管理器会提示其 XML 解析版本早于 Android Studio 安装的部分元数据;它仍可安装本项目锁定的 +NDK 与 CMake。该提示不改变产物使用的具体版本,后续升级 SDK 管理器时必须重新记录。 + +## 应用与规划依赖 + +| 依赖 | 固定版本/提交 | 来源 | 许可证 | 当前状态 | +| --- | --- | --- | --- | --- | +| AndroidX Core KTX | 1.17.0 | Google Maven | Apache-2.0 | M0 已引入 | +| AndroidX Activity KTX | 1.12.0 | Google Maven | Apache-2.0 | M0 已引入 | +| Room | 2.7.2 | Google Maven | Apache-2.0 | 为 M2 锁定,尚未引入 | +| DataStore Preferences | 1.1.7 | Google Maven | Apache-2.0 | 为 M4/M6 锁定,尚未引入 | +| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | `libretro/libretro-fceumm` | GPL-2.0-only | 为 M2 锁定,尚未编译 | +| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | `libretro/RetroArch` | MIT | 为 M2 锁定,尚未引入 | +| Oboe | tag `1.10.0`, commit `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | `google/oboe` | Apache-2.0 | 为 M3 锁定,尚未引入 | + +详细的 Git 来源和补丁数组由 [third_party/manifest.json](../third_party/manifest.json) 作为机器可读 +锁文件保存。依赖获取执行 `tools/fetch-third-party.ps1`;这个脚本只检出固定提交,检测到已有 +非锁定工作树会失败,不会覆盖它。 diff --git a/gradle.properties b/gradle.properties new file mode 100644 index 0000000..f90a875 --- /dev/null +++ b/gradle.properties @@ -0,0 +1,4 @@ +org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8 +org.gradle.parallel=true +android.useAndroidX=true +kotlin.code.style=official diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml new file mode 100644 index 0000000..2b9d01f --- /dev/null +++ b/gradle/libs.versions.toml @@ -0,0 +1,25 @@ +[versions] +agp = "8.13.2" +kotlin = "2.3.0" +androidxCore = "1.17.0" +androidxActivity = "1.12.0" +junit = "4.13.2" +androidxJunit = "1.3.0" +espresso = "3.7.0" +room = "2.7.2" +datastore = "1.1.7" +oboe = "1.10.0" + +[libraries] +androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidxCore" } +androidx-activity-ktx = { module = "androidx.activity:activity-ktx", version.ref = "androidxActivity" } +androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" } +androidx-room-ktx = { module = "androidx.room:room-ktx", version.ref = "room" } +androidx-datastore-preferences = { module = "androidx.datastore:datastore-preferences", version.ref = "datastore" } +junit = { module = "junit:junit", version.ref = "junit" } +androidx-junit = { module = "androidx.test.ext:junit", version.ref = "androidxJunit" } +androidx-espresso-core = { module = "androidx.test.espresso:espresso-core", version.ref = "espresso" } + +[plugins] +android-application = { id = "com.android.application", version.ref = "agp" } +kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" } diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar new file mode 100644 index 0000000..9bbc975 Binary files /dev/null and b/gradle/wrapper/gradle-wrapper.jar differ diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties new file mode 100644 index 0000000..36e4933 --- /dev/null +++ b/gradle/wrapper/gradle-wrapper.properties @@ -0,0 +1,8 @@ +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +distributionSha256Sum=20f1b1176237254a6fc204d8434196fa11a4cfb387567519c61556e8710aed78 +distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip +networkTimeout=10000 +validateDistributionUrl=true +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew new file mode 100644 index 0000000..40ef530 --- /dev/null +++ b/gradlew @@ -0,0 +1,41 @@ +#!/bin/sh +# +# Copyright © 2015 the original authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit +APP_NAME="Gradle" +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + +if [ -n "$JAVA_HOME" ] ; then + JAVACMD=$JAVA_HOME/bin/java +else + JAVACMD=java +fi + +if [ ! -x "$JAVACMD" ] ; then + echo "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH." >&2 + exit 1 +fi + +set -- \ + "-Dorg.gradle.appname=$APP_NAME" \ + -classpath "$CLASSPATH" \ + org.gradle.wrapper.GradleWrapperMain \ + "$@" + +exec "$JAVACMD" $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "$@" diff --git a/gradlew.bat b/gradlew.bat new file mode 100644 index 0000000..88136ef --- /dev/null +++ b/gradlew.bat @@ -0,0 +1,86 @@ +@rem +@rem Copyright 2015 the original authors. +@rem +@rem Licensed under the Apache License, Version 2.0 (the "License"); +@rem you may not use this file except in compliance with the License. +@rem You may obtain a copy of the License at +@rem +@rem https://www.apache.org/licenses/LICENSE-2.0 +@rem +@rem Unless required by applicable law or agreed to in writing, software +@rem distributed under the License is distributed on an "AS IS" BASIS, +@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +@rem See the License for the specific language governing permissions and +@rem limitations under the License. +@rem + +@if "%DEBUG%"=="" @echo off +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +set DIRNAME=%~dp0 +if "%DIRNAME%"=="" set DIRNAME=. +@rem This is normally unused +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Resolve any ".." in APP_HOME to make it shorter. +for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if %ERRORLEVEL% equ 0 goto execute + +echo. 1>&2 +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto execute + +echo. 1>&2 +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 + +goto fail + +:execute +@rem Setup the command line + +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* + +:end +@rem End local scope for the variables with windows NT shell +if %ERRORLEVEL% equ 0 goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of the _cmd.exe /c_ return code! +set EXIT_CODE=%ERRORLEVEL% +if %EXIT_CODE% equ 0 set EXIT_CODE=1 +if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE% +exit /b %EXIT_CODE% + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/settings.gradle.kts b/settings.gradle.kts new file mode 100644 index 0000000..66bce63 --- /dev/null +++ b/settings.gradle.kts @@ -0,0 +1,18 @@ +pluginManagement { + repositories { + google() + mavenCentral() + gradlePluginPortal() + } +} + +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + google() + mavenCentral() + } +} + +rootProject.name = "NESLite" +include(":app") diff --git a/third_party/manifest.json b/third_party/manifest.json new file mode 100644 index 0000000..b1cf031 --- /dev/null +++ b/third_party/manifest.json @@ -0,0 +1,34 @@ +{ + "format": 1, + "updated": "2026-09-12", + "sources": [ + { + "name": "FCEUmm libretro core", + "directory": "libretro-fceumm", + "url": "https://github.com/libretro/libretro-fceumm.git", + "commit": "236ccdfc911e84c60fea6b9d0699c2d440a8de14", + "license": "GPL-2.0-only", + "purpose": "M2 fixed emulator core", + "patches": [] + }, + { + "name": "libretro public header", + "directory": "libretro-headers", + "url": "https://github.com/libretro/RetroArch.git", + "commit": "0c9622896333ee62dc4326bbe8784a210ddeb03c", + "license": "MIT", + "purpose": "M2 fixed libretro API header", + "patches": [] + }, + { + "name": "Oboe", + "directory": "oboe", + "url": "https://github.com/google/oboe.git", + "tag": "1.10.0", + "commit": "a81bb9f87d4105b84b682685d3bfbb5beca371d1", + "license": "Apache-2.0", + "purpose": "M3 Android audio output", + "patches": [] + } + ] +} diff --git a/third_party/patches/README.md b/third_party/patches/README.md new file mode 100644 index 0000000..8c2a197 --- /dev/null +++ b/third_party/patches/README.md @@ -0,0 +1,9 @@ +# 本地补丁清单 + +M0 没有本地补丁。以后每个补丁必须以 `NNN-简短说明.patch` 形式放在此目录,并同时: + +1. 在 `../manifest.json` 对应源的 `patches` 数组登记文件名和 SHA-256; +2. 说明上游基准提交、目的、应用顺序与撤销方式; +3. 在 `docs/dependencies.md` 和许可证通知中更新受影响的来源/修改声明。 + +不能以未登记的工作区修改或手工复制的库替代补丁。 diff --git a/todo.md b/todo.md new file mode 100644 index 0000000..7cb82ed --- /dev/null +++ b/todo.md @@ -0,0 +1,250 @@ +# NESLite V1.0 待办事项 + +依据:[开发计划 V1.0](docs/development_plan_V1.0.md)。编制日期:2026-09-12。所有开发任务初始状态为未开始,本文不表示任何工程或实机验收已经完成。 + +## 1. 执行与勾选规则 + +1. **一个实现项交付一项可独立验证的能力或一份完整材料。** 任务通常控制在约半天至一天半;不把编码、编译、补测试分别拆成待办,也不把整个模块塞进一个实现项。阶段验收与发布材料单列,不按实现项工期衡量。 +2. **编号对应开发计划。** 例如 `M2-02a`、`M2-02b` 均属于计划的 `M2-02`;后缀只拆分工作,不改变所属阶段。每项均写明阶段内前置条件、交付结果和验收级别。 +3. **阶段依赖是共同前置条件。** M0 无阶段前置;M1~M9 依次依赖上一阶段门槛 G0~G8 通过,等价于计划中的累计依赖。条目内“无”仅表示没有额外的阶段内前置条件。列表顺序已按实际依赖排列,不要求父编号严格递增。 +4. **完成实现项不等于阶段通过。** 实现、对应局部验收及必要文档更新完成后才能勾选实现项;阶段 G 项还需满足明确的集成/实机门槛。设备缺失时保留 G 项未勾选,不能以编译成功或模拟输入替代真实手柄验收。 +5. **等待不阻止独立工作。** 前置未通过时,只能推进不依赖其结果的草稿或隔离实现;不能提交依赖未知接口的完成结论,也不能勾选依赖阶段的门槛。 +6. **状态与证据只记一次。** 未勾选项默认“未开始”;进行中、待实机或失败时在条目末附状态和原因。通过后附源码提交及报告位置;阶段报告引用这些记录,不复制同一测试。尚未建立的文档路径是交付目标。 +7. **范围和参数不暗改。** 保留计划的 F01~F14、M0~M9 及 0.1.x~1.0.0 路线。新需求另列后续版本;快进倍率、存档周期等计划允许校准的参数,在指定阶段形成记录并同步两份文档。 +8. **未定参数也有明确交付要求。** 计划未给数值的 ROM/存档包大小上限、轴阈值、连发频率、缓冲/日志容量,由对应实现项确定并记录数值、单位、默认值及超限行为;配置、文档和验收一致后才算完成,不用“适当”“合理”等词代替实际参数。 + +## 2. 分级验收与重跑规则 + +### 2.1 验收等级 + +等级表示验证范围,不是每项任务必须从 L0 到 L4 全部重跑。高等级可直接引用仍有效的低等级结果。每项中的完成标准定义最小必要行为;只有失败、未知影响或下表所列变更才扩大范围。 + +| 等级 | 使用场景 | 要做的验证 | 不自动包含 | +| --- | --- | --- | --- | +| L0 文档/材料检查 | 文档、清单、版本说明或材料整理 | 核对内容、编号、链接、版本与文件对应关系 | 编译、运行、游戏回归 | +| L1 局部验证 | 单一逻辑、构建配置、解析器或映射规则 | 受影响目标的编译/静态检查;用最少的正常和必要边界用例验证本项行为 | 全部单元测试、整应用实机流程、耐久测试 | +| L2 模块集成 | JNI、设备、文件系统、UI 或两个模块交接 | 受影响模块及直接相邻接口;一个代表样本的正常流程,加本次涉及的失败/取消分支 | 全 ROM 集、30 分钟运行、100 次存读档、20 轮循环 | +| L3 阶段验收 | G1~G7 的阶段出口;G0 为构建基线检查 | 本阶段新增能力的连贯路径,以及分配到该阶段的专项指标 | 其他已通过阶段的全部测试、发布全量回归 | +| L4 发布验收 | M8 的候选发布版与 G8 | 核对 F01~F14,执行冻结的兼容集和候选包关键流程,补齐缺失/失效的专项证据 | 不分影响地重复所有历史用例、设备和长测 | + +纯文案或排版改动用 L0;布局和焦点改动用对应页面的 L2;不为低影响改动编写仅重复实现的测试。新增或修复有状态逻辑时优先增加可复现行为测试,避免每个页面各写一套相同底层测试。 + +### 2.2 改动到验证范围的映射 + +本表的“重跑”针对已经实现并验收过的能力。首次开发按当前任务的 L1/L2 验证,完整 H 项到指定节点执行,不提前要求测试尚未实现的后续功能。同一轮连续修改先用局部验证排错,修改稳定后在阶段/发布门槛统一执行所需专项;不为每个函数或每次提交各跑一次长测。 + +| 改动 | 默认选择 | 扩大范围的条件 | +| --- | --- | --- | +| 文档、注释、无运行影响的说明 | L0 | 文档同时变更了产品行为时,转入对应实现项验收 | +| 游戏库/设置界面 | 对应 L1 或 L2;只跑改动页面和直接调用链 | 触及共享焦点、输入分发或会话控制时,补对应模块路径 | +| 映射、死区、来源合成、连发 | 输入 L1+改动链的 L2 | 改变断柄清理或设备识别时重跑 H-HOT;改变采样链时重跑 H-INPUT | +| 音频缓冲、重采样、时钟、快进 | 音频/时钟 L1+切换 L2 | 时钟或持续流行为变更,重跑完整 H-AV 及对应模式切换;不自动重跑游戏库或存档包测试 | +| 存档格式、提交/备份/恢复、序列化逻辑 | 存档 L1+集成 L2 | 重跑完整 H-SAVE;触及升级兼容时补 H-UPGRADE;槽位文案改动不触发 100 次循环 | +| 生命周期、Surface/音频重建、异步退出 | 受影响转换的 L2 | 改变后台/锁屏恢复时重跑 H-LIFE;改变资源释放或产生内存疑点时重跑 H-LONG | +| FCEUmm 提交、内核编译选项、libretro 宿主行为 | 内核对应完整集:冻结 ROM 集、H-AV、H-SAVE 和内核控制路径 | 改动涉及原生打包则补 H-NATIVE;影响无法界定时进入 L4 | +| 工具链、ABI、链接/原生依赖、APK 打包 | 受影响构建+H-NATIVE+实际包短路径 | 若改变运行库/优化行为,补受影响音频、状态或长时指标;仅重新签名不自动重跑 2 小时测试 | +| RC 后缺陷修复 | 复现用例、受影响模块及实际新包短路径 | 多模块影响无法界定或出现广泛回归时重跑 L4 | + +**停止规则:** 本次选定范围通过且没有新增失败、未解释的统计异常或影响疑点,就结束验证并继续下一项;不以“再保险”为理由重复同一范围。 + +### 2.3 专项验收只在指定节点执行 + +H 编号是可复用的验收记录,不是额外实现任务。L1/L2 用例覆盖到同一场景时可合并执行;同一长时间会话可同时采集速度、音频、内存等指标。使用同一结果覆盖多个指标时,必须满足各自样本、时长和环境要求。 + +| 专项 | 首次完整执行节点 | 固定口径 | +| --- | --- | --- | +| H-AV 音画与速度 | G3 | NTSC、PAL 各连续至少 30 分钟;每个连续 60 秒窗口和全程速度均为 99.5%~100.5%;以实际模拟时间/有效单调时间计算,排除加载、暂停、快进。预热后的正常前台段欠载目标为 0,无持续爆音及累积偏移;模式/设备切换另做短路径 | +| H-HOT 插拔 | G4 | 目标手机+X5 Lite,20 轮按住方向及 A/B 时断开再重连;每轮确认暂停、状态清空、配置匹配和用户继续后输入正常 | +| H-SAVE 存档 | G5 | 同一锁定内核完成总计 100 次手动存读档循环,10 个槽各 10 次,每次对照预定状态和校验值确认恢复;同时安排自动恢复点轮换、电池存档重载、导出再导入的必要分支验证,不对每种类型再各做 100 次。截断、校验错、哈希/版本错、空间不足以及临时写入/替换前/替换后终止各覆盖对应失败路径,有效提交和备份保持可恢复 | +| H-LIFE 后台/锁屏 | G7 | 后台切换 20 轮、锁屏/解锁 20 轮;无后台声音、黑屏或残留键。Surface/Activity 重建、音频路由变化及异常启动另按不同状态转换覆盖,不再各做 20 轮 | +| H-LONG 长时稳定性 | M8-02a | 至少两个代表样本,分别覆盖动作/滚屏与电池存档,每个 2 小时;无崩溃、ANR 或持续内存增长;每分钟记录 Java/native 内存和 PSS,检查预热后趋势 | +| H-INPUT 软件输入延迟 | M8-02b | 正常负载下至少 1,000 次事件,以同一单调时间域记录应用接收到首次内核采样;P95 ≤ 1 个实际模拟帧,排除暂停/绑定界面,不作为按键到屏幕总延迟 | +| H-NATIVE 原生兼容 | M8-03a、M8-03b 合并记录 | 最终包的每个原生库通过 ELF 和 APK 16 KB 对齐检查;4 KB/16 KB 环境均完成加载、运行、声音和保存恢复。记录实际 ABI/页大小,x86_64 运行不替代 arm64 发布库检查 | +| H-UPGRADE 安装升级 | M8-04a | 新安装和至少一个旧测试版本的同 ID/同签名覆盖升级;ROM 关联、收藏、设置、游戏存档均保留,即时存档按兼容策略恢复或保留并提示 | + +H-SAVE 的故障注入按不同失败路径选择代表样本;共用同一提交器的所有槽位不重复相同故障矩阵。需要触发自动周期时使用可控测试时钟验证状态转换,不靠重复等待增加测试时长;周期对真实帧时间的影响另在 M5 实测。 + +**证据复用条件:** 报告必须标明源码/内核提交、相关模块及依赖配置、设备系统、ROM 哈希、参数、结果和日志。M8 逐项记录自该报告后有哪些改动、为什么未影响该指标;模块、配置或环境已变或无法证明未受影响时,重跑对应 H 项。不能仅因“以前通过”就复用,也不能为每个新提交自动使全部证据失效。 + +**发布全量的含义:** G8 必须覆盖计划全部发布要求;冻结兼容集与候选包关键路径在 RC 上执行,长测和计数型测试可引用符合上述条件的证据。M9 的最终包必须再做一次短路径,但相同代码和配置的签名/版本元数据变化不自动触发全部长测。 + +## 3. 全程保持一致的行为约定 + +| 主题 | 固定约定 | +| --- | --- | +| 工程 | NESLite;单 `app`、Kotlin+原生 View;minSdk 28,compileSdk/targetSdk 36;AGP 8.13.2、Gradle 8.13、JDK 17;NDK r28 起选精确版本;发布 arm64-v8a | +| 内核与线程 | 固定 FCEUmm;单 ROM、单实例、玩家一;改变内核状态的操作全部在模拟线程;音频回调不执行内核或阻塞 I/O | +| 导入与身份 | 只导入 `.nes`;识别 iNES/NES 2.0;完整文件字节 SHA-256 作为身份;内部正式 ROM 位于 files 而非 cache | +| 显示与时钟 | 默认 4:3、最近邻;原始像素整数缩放独立;模拟速度读取内核时序,与手机刷新率解耦 | +| 快进 | M3 引擎支持、M4 绑定 RB、M6 提供设置;初始按住 2 倍且静音,松开/失焦/暂停/断柄取消;最终倍率在 G3 冻结 | +| 输入 | A/B 对应 NES A/B,X/Y 对应 A/B 连发,菜单/视图为 Start/Select,右摇杆按下为暂停菜单;键码来自 M1 实测;不占用视图+菜单长按;快读档不默认绑定易误触单键 | +| 存档阶段 | M2 只交付基础电池存档;M5 才承诺完整备份、即时存档和故障恢复;M4 不验收尚未实现的存档导航 | +| 存档规则 | 手动 10 槽、自动最近 3 份;变化电池存档初始每 10 秒提交、自动恢复点初始每 60 秒生成,M5 按实测冻结;暂停/退出补充提交;成功落盘才显示保存成功 | +| 读档与恢复 | 读档先备份当前状态及游戏存档;失败回滚,回滚失败安全重载;不同内核提交默认不自动读入;回前台/重连后由用户继续 | +| 游戏库 | M2 最小列表、M4 焦点导航、M6 完整列表;从列表移除只隐藏并保留存档,再导入同哈希恢复关联 | +| 后台与范围 | 后台不继续模拟;V1.0 不含联网、云存档、FDS、第二手柄完整体验、回溯、run-ahead 或切换内核;不增加商店上架工作 | + +## 4. 实现待办与阶段门槛 + +条目中的 **前置** 仅列阶段内依赖;共同阶段依赖见第 1 节。**完成** 同时限定交付内容和可观察结果。所有任务保留计划原父编号,便于回填进度。 + +G1~G8 的共同交付物为对应阶段 APK、源码提交、构建说明、验收记录和已知问题清单。构建说明等未变化时引用现有文件及版本即可,不另写重复副本;以下 G 项只补充各阶段特有的材料。 + +### M0:工程准备 + +- [x] **M0-02a 锁定本机构建环境**。前置:无。完成:核对 JDK/SDK/NDK/CMake,记录精确版本、安装位置和缺口;形成工具链及应用依赖版本清单。验收:L1,工具可调用且版本符合计划,清单无动态版本。证据:`docs/toolchain.md`、`docs/reports/m0-baseline.md`;Gradle 构建和原生链均已实际调用。 +- [x] **M0-01a 建立可构建的应用骨架**。前置:M0-02a。完成:初始化 Git、Wrapper、单 app、Kotlin/View 页面、CMake 和 JNI 空入口,将锁定版本写入工程配置,生成 arm64 调试 APK。验收:L1,目标构建成功且 APK 包含预期原生库。证据:`app/build/outputs/apk/debug/app-debug.apk`;确认包含 `lib/arm64-v8a/libneslite_jni.so`。 +- [x] **M0-01b 固定应用与数据身份**。前置:M0-01a。完成:确定显示名、applicationId、版本号/versionCode 规则、长期测试与发布签名延续策略;在需求文档登记数据目录约定。验收:L0+受影响配置的 L1,构建配置与记录相符。证据:`docs/identity.md`;APK 为 `org.neslite.app.debug`、`0.0.1-dev-debug`、min/target SDK 28/36。 +- [x] **M0-03a 固定上游来源**。前置:M0-01a。完成:登记 FCEUmm 完整提交、libretro 头文件及 Oboe 固定版本,建立依赖获取方式和本地补丁清单。验收:L1,按记录可取得对应源码;此项不要求内核已编译。证据:`third_party/manifest.json`;三个固定提交已由 `tools/fetch-third-party.ps1` 检出。 +- [x] **M0-03b 建立许可证清单**。前置:M0-03a。完成:逐项记录依赖来源、版本、许可证和待交付材料,建立 LICENSE/THIRD_PARTY_NOTICES 基线。验收:L0,已引入依赖无遗漏、记录与选定源码一致。证据:`LICENSE`、`THIRD_PARTY_NOTICES.md`、`docs/dependencies.md`。 +- [x] **M0-02b 编写可复现构建说明**。前置:M0-01b、M0-03a。完成:docs/build.md 记录从检出到 APK 的步骤、精确工具版本、ABI 和依赖获取;不依赖手工复制未知库。验收:L0;干净检出实际构建统一放在 G0,不在此重复。证据:`docs/build.md`;调试 APK 已构建。 +- [x] **M0-04a 建立需求与验收资源表**。前置:M0-01b。完成:docs/requirements.md 映射 F01~F14;列出设备待测参数和 ROM 来源/哈希/区域/Mapper/存档类型;登记 M2 至少 3 个样本的获取安排,其中一个有电池存档。验收:L0,已取得样本有使用依据,未齐资源列明缺口和取得办法,G2 前须齐备。证据:`docs/requirements.md`、`docs/reports/rom-inventory.md`。 +- [x] **M0-04b 建立按范围执行的检查入口**。前置:M0-01a、M0-04a。完成:本地入口可选择构建、局部测试、模块集成和阶段检查;原生测试接入可运行目标;docs/acceptance.md 和报告模板使用 L/H 编号。验收:L1,执行一个最小目标可获得结果,默认命令不启动全部耐久测试。证据:`tools/check.ps1`;固定 CTest 的原生 smoke target 通过。 + +- [ ] **G0 工程门槛**。前置:本阶段全部实现项。验收:L3 构建基线;从干净检出按说明构建调试 APK 一次,核对依赖可追溯、无未知库;记录资源缺口与取得办法。此处不要求产品级界面或实机运行报告。状态:进行中;上次 Gradle 构建发现 Java/Kotlin JVM 目标不一致,已修正为 17,尚待生成并核对调试 APK,详见 `docs/reports/m0-baseline.md`。 + +### M1/0.1.x:设备与手柄诊断 + +- [ ] **M1-01a 完成安装和 JNI 自检**。前置:无。完成:诊断页展示原生调用结果与库加载错误;应用可在目标手机启动。验收:L2,一次安装启动和一次 JNI 调用成功,错误可定位。 +- [ ] **M1-01b 展示真实设备基线**。前置:M1-01a。完成:读取机型、系统 API、ABI、页大小、屏幕尺寸和可用刷新率;未知值明确标记。验收:L2,与设备可读取信息核对,不按 MagicOS 名称推断硬件。 +- [ ] **M1-02a 枚举控制器能力**。前置:M1-01a。完成:展示名称、描述符、厂商/产品标识、输入源和轴范围;连接/移除时更新列表。验收:L2,一次接入和移除可观察,设备临时编号不作持久身份。 +- [ ] **M1-03a 建立实时按钮状态页**。前置:M1-02a。完成:显示 KeyEvent 按下/松开及组合状态,保留事件时间与来源。验收:L2,方向和 A/B 可同时按下,全部松开后状态清零。 +- [ ] **M1-03b 展示轴与重复上报**。前置:M1-03a。完成:展示 HAT、摇杆、扳机值,能辨认同一操作的按键/轴两种上报。验收:L2,各实际可用轴的往返变化可观察,未上报的能力不伪造。 +- [ ] **M1-03c 记录可回放输入序列**。前置:M1-03b。完成:按统一事件结构保存来源、时间、动作和值,记录有界;提供供后续逻辑测试读取的格式。验收:L1,一段组合输入记录读取后事件顺序和数值一致。 +- [ ] **M1-04a 清理异常输入状态**。前置:M1-03b。完成:失焦、设备移除时清空相应状态;重连创建新的会话关联。验收:L2,按住后拔出、失焦、重连各一条代表路径无残留;此时不做 20 轮插拔。 +- [ ] **M1-04b 导出诊断和实测键位表**。前置:M1-01b、M1-03c、M1-04a。完成:通过系统选择器导出设备与事件 JSON,写入 docs/controller-x5lite.md,记录安卓模式、硬件连发状态和厂商保留组合。验收:L2,导出可读且键位表对应实测事件。 + +- [ ] **G1 诊断门槛**。前置:本阶段全部实现项。验收:L3;在真实目标手机和 X5 Lite 完成“连接 → 组合输入 → 松开 → 按住拔出 → 重连”一次连贯检查,可复用本阶段有效实机记录。交付 0.1.x APK、源码提交、构建说明、设备 JSON、键位表和未覆盖项;重估后续工期。 + +### M2/0.2.x:内核、画面与基础操作 + +- [ ] **M2-01a 编译固定内核**。前置:无。完成:FCEUmm 链接到原生宿主,记录构建选项/补丁并冻结实际编译通过的提交。验收:L1,arm64 目标链接成功、导出入口与 API 版本可检查。 +- [ ] **M2-04a 建立单线程会话执行器**。前置:M2-01a。完成:单内核线程、有界命令队列、会话编号及 Idle/Loading/Paused/Running/Pausing/Stopping/Error 状态;定义命令完成通知。验收:L1,状态转换和重复/迟到命令用最小序列验证,旧会话不能被重新激活。 +- [ ] **M2-01b 实现环境协商**。前置:M2-04a。完成:按内核要求注册回调、目录、配置和玩家一设备;不支持请求返回失败,必要能力缺失阻止加载;形成支持清单。验收:L1,支持、不支持和缺少必要能力各验证一条不同分支。 +- [ ] **M2-01c 接通内核生命周期与 AV 信息**。前置:M2-01b。完成:在模拟线程初始化、加载、读取时序、运行、卸载和销毁;正确消费音频回调但暂不发声,使用单调时钟控制速度。验收:L2,由测试入口提供已准备的样本路径,验证加载、卸载及失败后重载;不依赖尚未完成的导入 UI。 +- [ ] **M2-02a 实现 ROM 流式导入**。前置:M2-04a。完成:SAF 读取、大小上限、iNES/NES 2.0 头校验、内部临时副本和完整文件 SHA-256;取消/读取失败清理临时文件。验收:L1+SAF 的 L2,正常头、损坏头、中文文件名和取消覆盖不同路径。 +- [ ] **M2-02b 提交内部文件与最小游戏索引**。前置:M2-02a。完成:正式 ROM 存在 files,Room 以哈希关联;重复内容去重、同名不同内容分开;最小列表能选择加载。验收:L2,两种重复场景不串档,content URI 不被当作原生路径。 +- [ ] **M2-02c 恢复导入中断的不一致数据**。前置:M2-02b。完成:启动时核对临时/未登记文件和缺失文件记录,提供恢复或明确失败状态,不误删有效数据。验收:L2,在文件提交后数据库登记前中断、正式文件缺失各注入一次。 +- [ ] **M2-03a 实现原生视频缓冲交接**。前置:M2-01c。完成:处理协商像素格式、宽高、pitch、重复帧和有界缓冲所有权,不保存失效指针。验收:L1,选择覆盖非紧密行跨度、重复帧和缓冲切换的最小输入集。 +- [ ] **M2-03b 显示保持比例的游戏画面**。前置:M2-03a。完成:GL 线程显示最新完整帧,默认 4:3/最近邻,支持原始像素整数缩放;丢显示帧不跳模拟帧。验收:L2,一个样本切换两种缩放,比例和缓冲复用正确。 +- [ ] **M2-04b 将基础手柄快照送入内核**。前置:M2-01c、M2-03b。完成:使用 M1 实测键码映射方向、A/B、Start/Select,按状态采样,跨 JNI 不逐帧搬图像。验收:L2,代表游戏可组合操作且松开生效;自定义映射留给 M4。 +- [ ] **M2-04c 接通控制命令和基础生命周期**。前置:M2-04b、M2-02b。完成:UI 通过队列启动/暂停/继续/重置/退出;后台、锁屏、失焦、断柄及 Surface 丢失暂停清理;重建只重接会话;前台资源就绪后由用户继续。验收:L2,正常控制流程和相关状态转换各覆盖一次,不做 20 轮循环。 +- [ ] **M2-04d 读取并提交基础电池存档**。前置:M2-04c。完成:按 ROM 哈希读取保存内存,在模拟线程取快照、文件线程写入;暂停/正常退出提交;成功写入后报告成功。验收:L2,一个电池存档样本退出再载入保留进度,另一个 ROM 不共享文件;不声明 M5 的完整故障保证。 + +- [ ] **G2 基础运行门槛**。前置:本阶段全部实现项。验收:L3;至少 3 个合法样本运行,其中一个支持电池存档;代表样本完成“加载 → 运行 → 暂停 → 继续 → 重置 → 退出 → 重载”,电池进度可恢复,损坏导入不影响现有数据。复用同轮样本检查,不对每个样本重复全部生命周期;交付 0.2.x APK、内核记录、docs/architecture.md 和兼容结果。 + +### M3/0.3.x:音频、时钟与快进 + +- [ ] **M3-01a 打开并管理 Oboe 流**。前置:无。完成:请求低延迟输出,检查实际参数,失败时按能力回退,停止时释放流。验收:L2,一次成功输出和一次受控回退,错误不导致内核无限运行。 +- [ ] **M3-01b 接入有界音频环形缓冲**。前置:M3-01a。完成:生产/消费解耦、欠载补静音和计数;回调使用预分配内存,不阻塞或做文件操作。验收:L1,环绕、空/满边界各覆盖,运行时确认回调只消费数据。 +- [ ] **M3-02a 完成采样率与格式适配**。前置:M3-01b。完成:按内核和设备实际采样率重采样,完成声道/格式转换,跨批次保持连续。验收:L1,不同采样率代表输入输出长度与连续性正确;无需枚举所有可能采样率。 +- [ ] **M3-02b 展示音频诊断参数**。前置:M3-02a。完成:记录内核/设备采样率、回调帧数、缓冲水位、欠载及重建次数,诊断采集有界。验收:L2,实际流参数与展示一致,欠载注入使对应计数变化。 +- [ ] **M3-03a 实现正常运行调度**。前置:M3-02a。完成:以单调时钟、内核时序和音频消费/水位调节推进;显示独立,无音频时切换时钟策略;静音不改变速度。验收:L1+L2,正常、无音频及静音各短路径,无挂起或失控追帧。 +- [ ] **M3-03b 采集速度与帧时间指标**。前置:M3-03a、M3-02b。完成:按实际时序累计模拟时间,分离加载/暂停/快进时间,输出窗口统计和帧时间记录。验收:L1,受控时间序列的计数和排除区间正确;30 分钟测量留给 G3。 +- [ ] **M3-04a 接入音量与静音控制**。前置:M3-03a。完成:UI 命令调整增益/静音,暂停停止输出,恢复不播放旧缓冲。验收:L2,一次音量、静音、暂停与恢复的组合路径,声音和速度符合状态。 +- [ ] **M3-04b 处理音频焦点变化**。前置:M3-04a。完成:失去焦点按策略暂停、清理输入并停止声音;重新获得焦点不自行继续游戏。验收:L2,一次失去/恢复焦点及退出竞态,旧会话无回调复活。 +- [ ] **M3-04c 重建音频设备输出**。前置:M3-04b。完成:路由/流断开后释放并重开,重新读取参数,清空旧音频并重建时间基线,失败时可留在安全暂停状态。验收:L2,可用路由切换和一次受控重开失败后可恢复。 +- [ ] **M3-04d 实现按住快进模式**。前置:M3-03b、M3-04c。完成:支持初始 2 倍静音快进;释放、暂停、失焦、断柄和退出均取消,恢复正常时重建音频与时钟基线。验收:L1+L2,以控制命令验证切换;正式 RB 绑定在 M4,不作为本项前置。 + +- [ ] **G3 可玩音画门槛**。前置:本阶段全部实现项。验收:L3+H-AV;同一批 NTSC/PAL 会话同时记录速度、声音、水位和帧时间,再做受影响模式/路由的短切换。冻结实测可用快进倍率,交付 0.3.x APK 及性能基线;重估剩余工期。 + +### M4/0.4.x:完整手柄操作 + +- [ ] **M4-01a 建立默认与通用映射**。前置:无。完成:把 M1 档案转为 X5 Lite 默认配置,标准 Android 手柄使用通用映射;支持 A/B 交换并保留厂商组合。验收:L1,档案匹配和默认动作正确;未知设备不套用错误专属配置。 +- [ ] **M4-01b 实现自定义绑定页面**。前置:M4-01a。完成:捕获待绑定输入、提示冲突、保存或取消、恢复默认;菜单始终保留可达入口。验收:L2,一个绑定、冲突、取消和恢复流程可完成,退出绑定模式不残留按键。 +- [ ] **M4-02a 合成独立来源并去重**。前置:M4-01a。完成:分别维护设备/轴/按键/触屏来源状态;相同动作重复上报不会重复触发菜单,释放一个来源不清除其他来源。验收:L1,用覆盖双来源按住/释放和轴键重复的最小事件序列;此阶段触屏来源可用测试输入。 +- [ ] **M4-02b 实现死区和方向规则**。前置:M4-02a。完成:轴按下/释放使用不同阈值,支持死区设置;左右或上下冲突时相应方向归零。验收:L1,阈值边界往返和相反方向序列结果确定,无边界抖动。 +- [ ] **M4-03a 实现 A/B 软件连发**。前置:M4-02b。完成:X/Y 对应 A/B 连发,周期按模拟时间推进,退出运行状态清理连发。验收:L1+L2,NTSC/PAL 时间口径一致;关闭硬件连发验证软件行为,再记录硬件连发单独表现。 +- [ ] **M4-03b 绑定暂停与快进动作**。前置:M4-01b、M4-03a。完成:右摇杆按下切换暂停菜单,RB 控制快进;单次命令按边沿触发,菜单键/视图键仍为 Start/Select,默认无易误触快速读档键。验收:L2,长按不重复开关菜单,RB 松开和断柄均结束快进。 +- [ ] **M4-04a 接通列表与菜单焦点导航**。前置:M4-03b。完成:最小游戏列表、暂停菜单和已存在设置页可用手柄移动、确认和返回;焦点不丢失。验收:L2,仅用手柄启动、暂停、继续、重置和退出;本项不要求尚未实现的存档 UI。 +- [ ] **M4-04b 持久化并恢复控制器档案**。前置:M4-01b、M4-04a。完成:DataStore 保存映射/死区等配置,以设备特征匹配,临时 deviceId 只在当前连接使用。验收:L2,一次重启和一次重连恢复配置,设备变号后仍正确关联。 + +- [ ] **G4 手柄门槛**。前置:本阶段全部实现项。验收:L3+H-HOT;引用输入回放结果,执行 20 轮真实插拔及全手柄运行路径,记录残留键/重复动作数为 0。交付 0.4.x APK、配置和操作说明;存档选择/读档导航延至 G5。 + +### M5/0.5.x:可靠存档与恢复 + +- [ ] **M5-01a 建立统一安全提交器**。前置:无。完成:不可变快照按 ROM 串行写入,同目录临时文件、刷新、校验、原子替换和有效备份;旧任务不能覆盖新版本。验收:L1+L2,一次提交、替换失败和乱序任务验证;完整故障矩阵集中在 G5。 +- [ ] **M5-01b 完善电池存档提交策略**。前置:M5-01a。完成:检测内容变化,按初始 10 秒周期及暂停/退出请求提交;无变化不重复写,成功落盘才通知成功。验收:L1+L2,可控时钟覆盖周期和无变化分支,实机测一次保存前后帧时间以冻结周期。 +- [ ] **M5-02a 定义并实现即时存档封装**。前置:M5-01a。完成:保存 ROM 哈希、内核名称/提交、格式版本、配置、时间、长度和校验值;在模拟线程帧边界序列化。验收:L1,封装往返和长度/校验异常可识别;更新 docs/save-format.md。 +- [ ] **M5-02b 实现 10 槽和缩略图快照**。前置:M5-02a。完成:10 个固定手动槽记录时间/缩略图,内容与元数据关联一致;覆盖使用安全提交器;暂停菜单提供基本槽位入口。验收:L2,首次保存和覆盖一个槽位结果正确,失败不显示新存档成功。 +- [ ] **M5-03a 实现自动恢复点轮换**。前置:M5-02b、M5-01b。完成:初始每 60 秒及暂停/退出请求自动快照,独立于手动槽,最多保留最近 3 份有效记录;新提交失败不挤掉旧记录。验收:L1+L2,可控时钟产生 4 份并核对轮换,实机测一次帧时间以冻结周期。 +- [ ] **M5-03b 记录异常会话与恢复候选**。前置:M5-03a。完成:启动/正常结束会话有持久标记,异常重启时列出有效恢复点而不自动运行游戏。验收:L2,一次正常退出及一次进程终止后,提示与候选状态不同且正确;连续崩溃保护在 M7 完善。 +- [ ] **M5-04a 校验读档并保护当前进度**。前置:M5-02b。完成:读档前检查哈希、内核提交、格式、配置和完整性,备份当前状态及电池存档;不同内核提交默认拒绝自动恢复并保留原件。验收:L1+L2,正确档及各不同拒绝分支不串档、不覆盖现有进度。 +- [ ] **M5-04b 完成读档失败回滚**。前置:M5-04a。完成:暂停后在模拟线程反序列化;失败恢复读档前快照,回滚也失败则安全重载有效电池存档;清空旧音视频、重建时钟。验收:L2,成功、反序列化失败和回滚失败各覆盖一次,内核未知状态不可继续运行。 +- [ ] **M5-04c 导出独立存档包**。前置:M5-03b、M5-04b。完成:通过 SAF 导出已提交存档及必要元数据,默认不含 ROM;明确导出失败和取消状态。验收:L2,一次成功导出及取消;包内容与选定游戏对应。 +- [ ] **M5-04d 校验并导入存档包**。前置:M5-04c。完成:限制路径、单项/总大小及格式,校验匹配后安全提交;替换前保留有效版本,失败不留下可误用记录。验收:L1+L2,导出包往返一次,越界路径和无效包被拒绝。 + +- [ ] **G5 存档门槛**。前置:本阶段全部实现项。验收:L3+H-SAVE;100 次循环和故障路径只按第 2 节总口径执行,引用已覆盖的有效分支结果。仅靠手柄完成“选择槽 → 保存 → 读档 → 继续 → 退出”;交付 0.5.x APK、存档格式、已冻结周期及恢复报告。 + +### M6/0.6.x:日常使用界面 + +- [ ] **M6-01a 完善游戏库查询和状态**。前置:无。完成:列表显示元数据,支持搜索、收藏和最近游玩;状态写入 Room 并在重启后恢复。验收:L2,一个包含中文长文件名的混合列表验证查询、收藏和最近记录。 +- [ ] **M6-01b 完成列表移除与重新关联**。前置:M6-01a。完成:移除仅隐藏条目并保留存档;重导入同哈希恢复原关联,同名不同内容仍独立。验收:L2,一次隐藏与重新导入后可找到原存档,无数据删除。 +- [ ] **M6-02a 提供显示设置页面**。前置:无。完成:可选择保持比例/原始整数缩放、最近邻/线性过滤;设置持久化并作用于游戏显示。验收:L2,一个样本逐项切换并重启确认,不重跑 ROM 兼容集。 +- [ ] **M6-02b 整合音频与手柄设置**。前置:M6-02a。完成:音量、静音、映射、死区、连发相关偏好和快进开关统一可访问;复用 M3/M4 实现,不重复建立状态来源。验收:L2,改动设置在当前会话和重启后生效,快进关闭后 RB 不加速。 +- [ ] **M6-03a 完善存档管理页面**。前置:无。完成:展示手动槽、自动恢复点、时间/缩略图、导入导出入口;手柄和触屏都能完成既有存档操作。验收:L2,一个游戏的管理流程与原存档服务结果一致;不重跑 H-SAVE。 +- [ ] **M6-03b 统一页面状态与错误反馈**。前置:M6-01b、M6-02b、M6-03a。完成:游戏信息及相关页面覆盖空、加载、失败、无手柄、长中文名;保存成功/失败与实际提交一致,有可用返回或重试入口。验收:L2,按不同页面状态选代表路径,共用组件只验一次。 +- [ ] **M6-04a 实现基础虚拟按键**。前置:无。完成:方向、A/B、Start/Select 支持多点触控、滑出/取消和与手柄来源合成;触屏暂停入口可达。验收:L1+L2,方向+动作、取消、触屏与手柄先后释放各一条路径,无残留。 +- [ ] **M6-04b 完成首次使用引导**。前置:M6-03b、M6-04a。完成:首次安装可理解如何导入、连接/测试手柄、开始、保存和退出;无手柄时可走纯触屏路径。验收:L2,清空测试应用数据后完成一次引导,不使用用户真实存档作清理对象。 + +- [ ] **G6 日常使用门槛**。前置:本阶段全部实现项。验收:L3;全手柄与纯触屏各完成一次“导入 → 开始 → 保存 → 退出 → 恢复”,可引用本阶段已录制的完整路径。验收新增页面和输入交接;H-HOT/H-SAVE 仍有效时不重复,失效时按第 2 节补测。交付 0.6.x Beta 与使用说明。 + +### M7/0.7.x:系统专项适配 + +- [ ] **M7-01a 统一系统返回处理**。前置:无。完成:采用 AndroidX 返回处理,运行中返回打开暂停菜单、菜单返回继续、设置返回上级、列表返回退出。验收:L2,每种页面状态各一次,系统手势和应用入口结果一致。 +- [ ] **M7-01b 处理返回与游戏状态交接**。前置:M7-01a。完成:返回/菜单动作与暂停确认、加载中、退出中协调,不重复执行或跳回已退出会话。验收:L1+L2,代表重复动作及加载/退出竞态无双会话或错误继续。 +- [ ] **M7-02a 适配横屏安全区域**。前置:无。完成:画面、菜单及虚拟键分别处理挖孔、系统栏和手势边缘,关键按钮可触达。验收:L2,目标设备实际布局下检查一次各不同布局,不改变模拟比例。 +- [ ] **M7-02b 验证设备可用刷新率**。前置:M7-02a。完成:记录每个可用刷新率模式的显示与模拟速度短样本,切换后仍按内核时序运行。验收:L2,各实际模式一条短路径;只有时钟/音频指标异常才触发 H-AV 重跑。 +- [ ] **M7-03a 完善后台与锁屏资源协调**。前置:M7-01b。完成:后台、锁屏、通知/来电导致焦点变化时暂停、静音、清输入并请求保存;回来先准备资源,由用户继续。验收:L2,不同原因各一条状态路径;20 轮循环统一在 G7。 +- [ ] **M7-03b 完善 Surface/Activity 与路由重建**。前置:M7-03a。完成:重建时重绑资源而不新增内核线程,处理音频重开与退出交错;不持有已销毁界面。验收:L2,各不同重建路径与一次退出竞态,无持续黑屏、旧声音或多线程实例。 +- [ ] **M7-04a 阻断异常启动循环**。前置:M7-03b。完成:进程重建从磁盘会话记录恢复选择,同一 ROM/状态连续异常时回列表,不自动重复加载故障内容。验收:L2,受控连续失败后仍可进入列表并启动另一有效游戏。 +- [ ] **M7-04b 完成限额诊断导出**。前置:M7-04a、M7-02b。完成:整合版本、设备、输入、帧率、音频、存档及原生错误记录;日志轮换有上限,导出不包含 ROM。验收:L1+L2,超限轮换和一次导出可读,日志能对应当前会话。 + +- [ ] **G7 系统门槛**。前置:本阶段全部实现项。验收:L3+H-LIFE;后台和锁屏分别 20 轮,其他重建/异常启动引用有效分支记录。若 M7 修改使 H-HOT、H-AV 或 H-SAVE 失效,只补对应专项;交付 0.7.x APK、MagicOS 10 兼容报告与未覆盖条件。 + +### M8/0.9.x:候选发布与覆盖核对 + +- [ ] **M8-01a 冻结候选版和验收集合**。前置:无。完成:固定功能、源码、内核、依赖和配置;建立 F01~F14 到有效证据的索引,列出需重跑项目;冻结至少 12 个有权使用的代表样本,覆盖计划指定 Mapper/区域/文件头/电池存档维度。验收:L0,记录完整且不移除失败样本规避门槛。 +- [ ] **M8-01b 执行 RC 兼容集与关键路径**。前置:M8-01a。完成:在候选包运行冻结样本的预定步骤/自检,覆盖输入、音频、暂停、保存恢复、退出等产品主链;H-SAVE/H-HOT/H-LIFE 仅补 M8-01a 标记失效或缺失的项目。验收:L4 的兼容/功能部分,结果可定位到 ROM 和版本,不对每个 ROM 重复全部专项矩阵。 +- [ ] **M8-02a 完成长时稳定性验收**。前置:M8-01a。完成:执行 H-LONG 并分析崩溃、ANR、内存趋势;已有满足同样口径且仍有效的记录可引用。验收:L4 的 H-LONG;如需补 H-AV,可选满足区域要求的同一会话合并采集。 +- [ ] **M8-02b 完成软件输入延迟验收**。前置:M8-01a。完成:执行 H-INPUT,记录时间域、样本来源、P95 与帧时长;汇总速度/音频统计的有效性。验收:L4 的 H-INPUT 及 H-AV 证据核对,只补失效或缺失部分。 +- [ ] **M8-03a 检查发布原生库与打包对齐**。前置:M8-01a。完成:清点候选 APK 中 FCEUmm/JNI/音频及运行库,逐库检查 ELF 和最终 APK 16 KB 对齐,记录工具版本。验收:L4 的 H-NATIVE 静态部分,无遗漏库或不合格结果。 +- [ ] **M8-03b 验证页大小与最低系统环境**。前置:M8-03a。完成:在实际 4 KB/16 KB 环境做原生运行、声音、保存恢复;API 28 做安装、导入、运行和保存冒烟,记录 ABI 与环境限制。验收:L4 的 H-NATIVE 运行部分+API 28 短路径,不扩展到每个 Android 版本。 +- [ ] **M8-04a 验证新安装与覆盖升级**。前置:M8-01a。完成:执行 H-UPGRADE,核对 Room/设置迁移和存档兼容;保留至少一个可复用旧版本数据集。验收:L4 的 H-UPGRADE,签名/ID/版本记录与实际包一致。 +- [ ] **M8-04b 准备候选交付材料**。前置:M8-01b、M8-02a、M8-02b、M8-03b、M8-04a。完成:整理对应源码、依赖/补丁、许可证、原生符号、构建及使用说明、报告和已知问题;引用前述任务汇总后的有效专项结果。验收:L0,材料版本和测试证据一致,不在材料整理项中重跑测试。 + +- [ ] **G8 发布候选门槛**。前置:本阶段全部实现项。验收:L4 汇总;F01~F14、全部 H 项、环境和发布材料均有有效结果,无阻断/高优先级缺陷,其他问题逐项记录处理结论。门槛只审查并合并证据,不再启动第二轮相同全量测试;有修复时按第 2 节确定重跑范围。 + +### M9/1.0.0:正式交付 + +- [ ] **M9-01a 核对范围与正式版本信息**。前置:无。完成:确认 G8 结论、已知问题和交付范围,设置 1.0.0 与递增 versionCode,保持 applicationId 和签名策略。验收:L0+受影响版本配置的 L1。 +- [ ] **M9-01b 固定发布源码版本**。前置:M9-01a。完成:建立发布源码标记,记录与 RC 的全部差异;依赖、内核和构建配置均可追溯。验收:L0,差异若影响行为则先按第 2 节更新 G8 证据。 +- [ ] **M9-02a 生成正式签名交付包**。前置:M9-01b。完成:生成 NESLite-1.0.0-arm64-v8a.apk、SHA-256、源码包、对应符号及必要混淆映射;私钥不进入仓库或源码包。验收:L1,校验和、签名、ABI、版本和符号对应;正式包对齐检查因产物变化重新执行。 +- [ ] **M9-02b 完成交付说明与许可证材料**。前置:M9-02a。完成:最终说明涵盖构建、导入、手柄、保存/导出/恢复、兼容性及已知问题;源码和依赖许可证材料对应正式版本。验收:L0,交付文件齐全且不存在失效引用。 +- [ ] **M9-03a 验证正式 APK 短路径**。前置:M9-02b。完成:在目标设备实际正式包上完成安装、导入/加载、输入、声音、暂停、保存恢复和退出。验收:L2,每条主链一次;若仅签名/版本元数据变化,不自动重复全部 H 项。 +- [ ] **M9-03b 归档交付证据**。前置:M9-03a。完成:归档正式 APK 校验和、源码标记、工具链、报告、符号和后续问题清单,检查与实际交付文件对应。验收:L0,不重新执行已经通过的运行测试。 + +- [ ] **G9 正式交付门槛**。前置:本阶段全部实现项。验收:L0 交付核对;G8 结果仍有效、最终包短路径通过、计划第 9 节全部材料齐备,才记录应用 1.0.0 完成。任何必需实机/发布指标缺失均保留未完成状态。 + +## 5. 需求完成位置速查 + +此表是索引,不形成第二套待办或重复验收。具体行为与数量以上文条目和专项口径为准。 + +| 计划需求 | 实现位置 | 功能完成门槛 | +| --- | --- | --- | +| F01 导入与文件识别 | M2-02a~M2-02c | G2 | +| F02 游戏库 | M2-02b、M6-01a~M6-01b | G6 | +| F03 游戏控制 | M2-01c、M2-04a~M2-04d | G2 | +| F04 显示与过滤 | M2-03a~M2-03b、M6-02a | G6 | +| F05 音频与时序 | M3 全部,M7 的系统联调 | G3;系统联调 G7 | +| F06 映射与标准手柄 | M1 诊断、M4-01a~M4-01b、M4-04b | G4 | +| F07 输入细节与手柄导航 | M4-02a~M4-04b、M5 槽位联验 | G4;存档导航 G5 | +| F08 快进 | M3-04d、M4-03b、M6-02b | G4;设置入口 G6 | +| F09 游戏/即时/自动存档 | M2-04d、M5-01a~M5-03b | G5 | +| F10 存档导入导出与恢复 | M5-04a~M5-04d | G5 | +| F11 生命周期与异常恢复 | M2-04c、M3-04b~M3-04c、M5-03b、M7 | G7 | +| F12 虚拟按键 | M6-04a~M6-04b | G6 | +| F13 诊断 | M1、M3-02b/M3-03b、M7-04b | G7 | +| F14 原生兼容与交付 | M0 基线、M8-03a~M8-04b、M9 | G8;最终交付 G9 | + +所有需求在功能阶段通过后,仍须进入 G8 的发布覆盖核对;核对复用有效证据,不等于把每项的全部历史测试重新执行一遍。 diff --git a/tools/check.ps1 b/tools/check.ps1 new file mode 100644 index 0000000..5f64a83 --- /dev/null +++ b/tools/check.ps1 @@ -0,0 +1,75 @@ +[CmdletBinding()] +param( + [ValidateSet('Build', 'Local', 'Module', 'Stage')] + [string]$Scope = 'Build' +) + +$ErrorActionPreference = 'Stop' +$root = Split-Path -Parent $PSScriptRoot +$sdkRoot = if ($env:ANDROID_HOME) { $env:ANDROID_HOME } else { 'C:\Users\shenw_o246oq4\AppData\Local\Android\Sdk' } +$bundledJdk = Join-Path $root '.toolchains\jdk-17.0.17+10' +$env:JAVA_HOME = if ($env:JAVA_HOME -and (Test-Path (Join-Path $env:JAVA_HOME 'bin\java.exe'))) { $env:JAVA_HOME } else { $bundledJdk } + +if (-not (Test-Path (Join-Path $env:JAVA_HOME 'bin\java.exe'))) { + throw 'JDK 17 not found. Set JAVA_HOME to the pinned JDK; see docs/build.md.' +} +$javaExecutable = Join-Path $env:JAVA_HOME 'bin\java.exe' +$javaVersionProcess = New-Object System.Diagnostics.Process +$javaVersionProcess.StartInfo = New-Object System.Diagnostics.ProcessStartInfo +$javaVersionProcess.StartInfo.FileName = $javaExecutable +$javaVersionProcess.StartInfo.Arguments = '-version' +$javaVersionProcess.StartInfo.UseShellExecute = $false +$javaVersionProcess.StartInfo.RedirectStandardError = $true +$javaVersionProcess.StartInfo.CreateNoWindow = $true +$null = $javaVersionProcess.Start() +$javaVersion = $javaVersionProcess.StandardError.ReadToEnd() +$javaVersionProcess.WaitForExit() +if ($javaVersionProcess.ExitCode -ne 0) { + throw "Could not query JDK version at ${javaExecutable}." +} +if ($javaVersion -notmatch 'version "17\.') { + throw "JDK 17 is required, but JAVA_HOME resolves to: $javaVersion" +} +if (-not (Test-Path (Join-Path $sdkRoot 'platforms\android-36.1'))) { + throw "Android SDK Platform 36.1 not found at $sdkRoot. See docs/build.md." +} + +$env:ANDROID_HOME = $sdkRoot +$env:ANDROID_SDK_ROOT = $sdkRoot +$env:Path = "$env:JAVA_HOME\bin;$env:Path" +$gradle = Join-Path $root 'gradlew.bat' +$cmake = Join-Path $sdkRoot 'cmake\3.22.1\bin\cmake.exe' + +function Invoke-AppBuild { + & $gradle ':app:assembleDebug' + if ($LASTEXITCODE -ne 0) { throw 'Debug APK build failed.' } +} + +function Invoke-LocalTest { + & $gradle ':app:testDebugUnitTest' + if ($LASTEXITCODE -ne 0) { throw 'Local unit test failed.' } +} + +function Invoke-NativeTest { + if (-not (Test-Path $cmake)) { throw "Pinned Android CMake was not found: $cmake" } + $buildDir = Join-Path $root '.build\native-tests' + $ctest = Join-Path (Split-Path -Parent $cmake) 'ctest.exe' + & $cmake -S (Join-Path $root 'app\src\main\cpp') -B $buildDir + if ($LASTEXITCODE -ne 0) { throw 'Native test configuration failed.' } + & $cmake --build $buildDir --config Debug + if ($LASTEXITCODE -ne 0) { throw 'Native test build failed.' } + & $ctest --test-dir $buildDir -C Debug --output-on-failure + if ($LASTEXITCODE -ne 0) { throw 'Native smoke test failed.' } +} + +Push-Location $root +try { + switch ($Scope) { + 'Build' { Invoke-AppBuild } + 'Local' { Invoke-LocalTest } + 'Module' { Invoke-NativeTest; Invoke-LocalTest } + 'Stage' { Invoke-AppBuild; Invoke-NativeTest; Invoke-LocalTest } + } +} finally { + Pop-Location +} diff --git a/tools/fetch-third-party.ps1 b/tools/fetch-third-party.ps1 new file mode 100644 index 0000000..55dd361 --- /dev/null +++ b/tools/fetch-third-party.ps1 @@ -0,0 +1,41 @@ +[CmdletBinding()] +param() + +$ErrorActionPreference = 'Stop' +$root = Split-Path -Parent $PSScriptRoot +$sourceRoot = Join-Path $root 'third_party\sources' +New-Item -ItemType Directory -Force -Path $sourceRoot | Out-Null + +function Get-PinnedRepository { + param( + [Parameter(Mandatory)] [string]$Name, + [Parameter(Mandatory)] [string]$Url, + [Parameter(Mandatory)] [string]$Commit, + [string[]]$SparsePath = @() + ) + + $target = Join-Path $sourceRoot $Name + if (Test-Path $target) { + $actual = (& git -C $target rev-parse HEAD).Trim() + if ($actual -eq $Commit) { + Write-Output "$Name is already locked at $Commit" + return + } + throw "$target exists at $actual, not locked commit $Commit. Resolve it manually; this script never overwrites sources." + } + + & git clone --filter=blob:none --no-checkout $Url $target + if ($LASTEXITCODE -ne 0) { throw "Could not clone $Name." } + if ($SparsePath.Count -gt 0) { + & git -C $target sparse-checkout init --cone + & git -C $target sparse-checkout set --no-cone @SparsePath + } + & git -C $target fetch --depth 1 origin $Commit + if ($LASTEXITCODE -ne 0) { throw "Could not fetch locked commit for $Name." } + & git -C $target checkout --detach $Commit + if ($LASTEXITCODE -ne 0) { throw "Could not check out locked commit for $Name." } +} + +Get-PinnedRepository -Name 'libretro-fceumm' -Url 'https://github.com/libretro/libretro-fceumm.git' -Commit '236ccdfc911e84c60fea6b9d0699c2d440a8de14' +Get-PinnedRepository -Name 'libretro-headers' -Url 'https://github.com/libretro/RetroArch.git' -Commit '0c9622896333ee62dc4326bbe8784a210ddeb03c' -SparsePath @('libretro-common/include/libretro.h') +Get-PinnedRepository -Name 'oboe' -Url 'https://github.com/google/oboe.git' -Commit 'a81bb9f87d4105b84b682685d3bfbb5beca371d1'