starcel 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ # Generated by build.py
2
+ /dist/
3
+ /README.md
4
+ /LICENSE
5
+ /src/starcel/scripts/
@@ -0,0 +1,173 @@
1
+ STARCEL ALPHA COMMUNITY LICENSE
2
+ Version 3.0, 22 February 2026
3
+
4
+ Copyright (C) 2026 Nicholas Maleki.
5
+ Formerly developed under Recursion Computing, LLC (inactive).
6
+ All rights reserved.
7
+
8
+ This software is dual-licensed under:
9
+
10
+ (1) The Starcel Community License v3.0 (this document); OR
11
+ (2) A Commercial License obtained from Nicholas Maleki
12
+ by contacting nick@recursion.is.
13
+
14
+ Everyone is permitted to copy and distribute verbatim copies
15
+ of this license document, but changing it is not allowed.
16
+
17
+ Preamble
18
+
19
+ The Starcel Alpha Community License is a source-available license
20
+ designed to encourage adoption by individual developers,
21
+ researchers, and early-stage builders, while protecting the
22
+ Program from large-scale commercial exploitation, algorithmic
23
+ extraction, managed-service monetization, and competitive
24
+ enclosure.
25
+
26
+ This License permits broad usage for individuals and startups,
27
+ while requiring commercial engagement for large-scale or
28
+ enterprise monetization.
29
+
30
+ This License is not an OSI-approved open source license.
31
+
32
+ TERMS AND CONDITIONS
33
+
34
+ 1. Definitions.
35
+
36
+ "Licensor" means Nicholas Maleki.
37
+
38
+ "Program" means any work licensed under this License,
39
+ including its source code, architecture, and algorithms.
40
+
41
+ "Production Use" means any use connected to revenue
42
+ generation, internal business operations, commercial
43
+ infrastructure, or commercial advantage.
44
+
45
+ "Service Deployment" means making the Program available
46
+ to third parties via SaaS, API, hosting platform, cloud
47
+ service, embedded infrastructure, or similar mechanism.
48
+
49
+ "Competitive Offering" means a product or service that
50
+ substantially replicates or replaces the core functionality,
51
+ algorithmic structure, or commercial purpose of the Program.
52
+
53
+ "Algorithmic Derivative" means any implementation in any
54
+ programming language that materially reproduces or adapts
55
+ the unique algorithms, computational structures, model
56
+ designs, or system architectures embodied in the Program.
57
+
58
+ 2. Permitted Use.
59
+
60
+ You may use, modify, and experiment with the Program
61
+ for any lawful purpose, including commercial experimentation,
62
+ subject to the restrictions below.
63
+
64
+ 3. Revenue Reporting Threshold.
65
+
66
+ If your organization generates more than $250,000 USD
67
+ in annual gross revenue and the Program contributes
68
+ materially to your operations, you must notify Licensor
69
+ within 30 days by contacting nick@recursion.is.
70
+
71
+ Continued Production Use or Service Deployment beyond
72
+ that threshold requires written confirmation or execution
73
+ of a Commercial License.
74
+
75
+ 4. Managed Service and Enterprise Restriction.
76
+
77
+ You may not:
78
+
79
+ a) Offer the Program as a managed service;
80
+ b) Embed it in enterprise infrastructure;
81
+ c) Offer it as a hosted or API-based platform;
82
+ d) Use it as a core feature of a commercial product;
83
+
84
+ without obtaining a Commercial License.
85
+
86
+ 5. Anti-Competitive Use Restriction.
87
+
88
+ You may not use the Program to develop, operate,
89
+ or assist in creating a Competitive Offering at
90
+ commercial scale without a Commercial License.
91
+
92
+ 6. Algorithm Extraction Restriction.
93
+
94
+ You may not distribute, sublicense, sell, publish,
95
+ or incorporate any Algorithmic Derivative of the
96
+ Program into other software projects without prior
97
+ written confirmation from Licensor via:
98
+
99
+ nick@recursion.is
100
+
101
+ This clause applies regardless of whether the
102
+ original source code is copied verbatim.
103
+
104
+ 7. Distribution of Modified Versions.
105
+
106
+ You may distribute modified versions of the Program
107
+ provided that you:
108
+
109
+ a) Preserve attribution to Nicholas Maleki;
110
+ b) Clearly mark substantial modifications;
111
+ c) Include this License in full.
112
+
113
+ 8. Trademark and Branding.
114
+
115
+ The name "Starcel" and Logo may be used to truthfully describe
116
+ usage of the Program.
117
+
118
+ However:
119
+
120
+ a) You may not misrepresent authorship.
121
+ b) You may not modify the Starcel branding beyond
122
+ recognition.
123
+ c) You may not reuse the Starcel name, marks, or
124
+ branding for unrelated projects.
125
+ d) You may not imply endorsement without written
126
+ permission.
127
+
128
+ All trademark rights remain exclusively with Licensor.
129
+
130
+ 9. Contributor License Agreement (CLA).
131
+
132
+ By submitting contributions, you grant Licensor
133
+ a perpetual, worldwide, irrevocable, sublicensable
134
+ license to use, relicense, and commercialize your
135
+ contributions.
136
+
137
+ Contributors represent they have authority to grant
138
+ such rights.
139
+
140
+ 10. Patent Grant and Defensive Termination.
141
+
142
+ Each contributor grants a royalty-free patent license
143
+ covering patent claims necessarily infringed by their
144
+ contribution.
145
+
146
+ If you initiate patent litigation alleging infringement
147
+ by the Program, all rights under this License terminate
148
+ immediately.
149
+
150
+ 11. Reservation of Rights and Discretionary Termination.
151
+
152
+ Licensor reserves the right to terminate this License,
153
+ in whole or in part, for any reason or no reason,
154
+ upon written notice.
155
+
156
+ Upon termination, all rights granted herein cease
157
+ immediately unless otherwise specified in writing.
158
+
159
+ 12. Anti-Circumvention.
160
+
161
+ You may not impose technological measures that restrict
162
+ recipients from exercising rights granted under this License.
163
+
164
+ 13. Disclaimer of Warranty.
165
+
166
+ THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
167
+
168
+ 14. Limitation of Liability.
169
+
170
+ IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY DAMAGES
171
+ ARISING FROM USE OF THE PROGRAM.
172
+
173
+ END OF TERMS AND CONDITIONS
@@ -0,0 +1,266 @@
1
+ Metadata-Version: 2.4
2
+ Name: starcel
3
+ Version: 0.1.0a1
4
+ Summary: A Python-controlled 3D spreadsheet built on Unreal Engine 4. Installs the Python scripts and a launcher that downloads the latest Starcel build from GitHub.
5
+ Project-URL: Homepage, https://github.com/recursionis/starcel
6
+ Project-URL: Source, https://github.com/recursionis/starcel
7
+ Project-URL: Releases, https://github.com/recursionis/starcel/releases
8
+ Project-URL: Patreon, https://www.patreon.com/RecursionIs
9
+ Author: RecursionIs
10
+ License-File: LICENSE
11
+ Keywords: 3d,education,spreadsheet,unreal-engine,visualization
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Win32 (MS Windows)
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Education
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: License :: Other/Proprietary License
18
+ Classifier: Operating System :: Microsoft :: Windows
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Topic :: Scientific/Engineering :: Visualization
22
+ Requires-Python: >=3.9
23
+ Requires-Dist: comtypes; sys_platform == 'win32'
24
+ Requires-Dist: dill
25
+ Requires-Dist: fast-autocomplete[levenshtein]
26
+ Requires-Dist: gputil
27
+ Requires-Dist: imageio
28
+ Requires-Dist: kingdon
29
+ Requires-Dist: matplotlib
30
+ Requires-Dist: mpmath
31
+ Requires-Dist: numba
32
+ Requires-Dist: numpy
33
+ Requires-Dist: opencv-python
34
+ Requires-Dist: psutil
35
+ Requires-Dist: py-cpuinfo
36
+ Requires-Dist: pymupdf
37
+ Requires-Dist: pynput
38
+ Requires-Dist: pystubgen
39
+ Requires-Dist: pywin32; sys_platform == 'win32'
40
+ Requires-Dist: requests
41
+ Requires-Dist: scikit-image
42
+ Requires-Dist: scikit-learn
43
+ Requires-Dist: sympy
44
+ Requires-Dist: wmi; sys_platform == 'win32'
45
+ Description-Content-Type: text/markdown
46
+
47
+ # Starcel <sub><img src="https://raw.githubusercontent.com/recursionis/starcel/master/Images/branding/icon-padded.png" alt="logo"></sub>
48
+ Hi! I'm Nick, the developer of Starcel
49
+
50
+
51
+ ## What is it?
52
+ A Python controlled 3D spreadsheet. A full Unreal Engine 4 instance with Chaos physics. Support for Client and Server. It can be used as a visualization or education tool.
53
+
54
+ Currently, Starcel is an Unreal Engine 4.27Chaos Client and Server which can be controlled with Python 3.9. There is 3D spreadsheet functionality, a Python calculation engine, everything Unreal engine offers, and there are many more features planned. It is very powerful.
55
+
56
+ This project is intended for content creators, hobbyists, developers, spreadsheet users, physicists, engineers, scientists, gamers, unreal engine prototypes, and more.
57
+
58
+
59
+ ## Please [donate](https://www.patreon.com/RecursionIs) to keep this project running!
60
+ You can donate on [Paypal](https://www.paypal.com/paypalme/RecursionIs) or [Patreon](https://www.patreon.com/RecursionIs)
61
+
62
+
63
+ ## Quickstart
64
+ The current release includes the client, the server, and the no-editor for Windows. Each compiled source is ~1GB.
65
+ The full Unreal Engine Starcel source project folder is quite a large download, >50GB. The project files on github are ~1GB, check the .gitignore to see what is missing.
66
+
67
+ You need to use Visual Studio 2019 for compiling ([download community edition](https://aka.ms/vs/16/release/vs_community.exe)). I recommend [PyCharm Community](https://www.jetbrains.com/pycharm/download/?section=windows) for editing until IDE support is added.
68
+
69
+ Compiled versions of Python 3.9 can be downloaded from here https://www.python.org/downloads/release/python-3913/, newer versions of specifically Python 3.9 should work, but need to be compiled from Python source. The unreal_engine package is not installed to Python permanently, but it is installed at runtime, so it does not need to be pip-installed. The `Content/Scripts/unreal_engine` folder includes all necessary stubs and empty classes for intellisense.
70
+
71
+ You can manually install the necessary packages directly using `python.exe -m pip install -r requirements.txt`.
72
+
73
+ The default Unreal Engine map contains a PyActor which loads main.py and the class Main when the map starts up. Both the server and the client will run this file separately. The line ``if KismetSystemLibrary.IsDedicatedServer():`` lets you define client and server specific code. You can create more PyActors or even use Python from the UE console by clicking ` and typing "py.".
74
+
75
+ Use `spawn_pyactor` to create an object that runs a Python class.
76
+
77
+ Create a Text object by double clicking Enter. Once created, you can use =py() to run any Python command.
78
+
79
+ The state of the world is not saved in main.py or elsewhere, you will need to make changes there directly or copy your changes from the world elsewhere to save. This will be changed in the future.
80
+
81
+ Add the following to "C:\Program Files\Epic Games\UE_4.27\Engine\Config\BaseEngine.ini"
82
+ ```
83
+ [PlatformPaths]
84
+ UnrealBuildTool=Engine/Binaries/DotNET/UnrealBuildTool.exe
85
+ ```
86
+
87
+ You may need to set the UE_PYTHON_DIR, PYTHONPATH, and PYTHONHOME environment variables to the location of your python installation, `C:\Users\nicho\AppData\Local\Programs\Python\Python39\` or `C:\Program Files\Python39` for example.
88
+
89
+ You may need to move Python3.dll and python39.dll into C:\Program Files\Epic Games\UE_4.27\Engine\Binaries\ThirdParty\Python3
90
+
91
+ Replace C:\UE_4.27Chaos_Source\Engine\Binaries\ThirdParty\Python3 with a copy of your Python3.9 instance.
92
+
93
+ ## Startup map and mod paks
94
+ You can set which map opens first and which mod `.pak` files load in the ini files. You don't need any command-line arguments.
95
+
96
+ **Startup map:** `Config/DefaultEngine.ini`
97
+ ```ini
98
+ [/Script/EngineSettings.GameMapsSettings]
99
+ GameDefaultMap=/Game/Maps/StaringAtSkyMap.StaringAtSkyMap
100
+ EditorStartupMap=/Game/Maps/StaringAtSkyMap.StaringAtSkyMap
101
+ ```
102
+ You can also change these in the editor under Project Settings → Maps & Modes.
103
+
104
+ **Mod paks:** `Config/DefaultGame.ini`
105
+ ```ini
106
+ [/Script/Starcel9.StarcelPakLoader]
107
+ ; mount every .pak in this folder
108
+ +ModPakDirs=Mods
109
+ ; or list paks one by one
110
+ +ModPaks=Mods/StarcelMapTest1-WindowsNoEditor.pak
111
+ ; optional, overrides GameDefaultMap
112
+ StartupMap=SunTemple
113
+ ```
114
+ Keep comments on their own lines. UE doesn't strip a `;` comment that comes after a value.
115
+ - Relative paths are relative to the project folder. In a packaged build, that's `WindowsNoEditor/Starcel9/`, so the default mods folder is `WindowsNoEditor/Starcel9/Mods/`.
116
+ - A pak can be a full packaged build of another UE 4.27 project, such as `MyMap-WindowsNoEditor.pak`. Its `/Game/...` assets become loadable without overriding Starcel's own files.
117
+ - `StartupMap` takes a short name (`SunTemple`) that is looked up in the mounted paks, or a full path (`/Game/Maps/SunTemple`).
118
+ - To change these settings in a packaged build without repackaging, put the same section in `WindowsNoEditor/Starcel9/Saved/Config/WindowsNoEditor/Game.ini`.
119
+ - Mod paks only load in packaged builds. The editor can't load cooked content.
120
+
121
+ The command line still works and takes priority: `Starcel9.exe SunTemple -ModPak="C:/path/to/MyMap-WindowsNoEditor.pak"` (see `test-pakmap.bat`). A map named on the command line is used instead of `StartupMap`. Paks from `-ModPak` are mounted in addition to the ones in the ini.
122
+
123
+ While the game is running, open the console (\`) and run `Starcel.LoadPakMap "C:/path/to/File.pak" [MapName]`. Blueprints can call `Mount Map Pak` / `Mount Pak And Open Map`.
124
+
125
+ Don't put mod paks in `Content/Paks`. The engine's automatic pak mounting expects paks built from this project, and it would stop the loose (non-pak) game files from loading.
126
+
127
+
128
+ ## Questions, Issues, and Support
129
+ Most everything you will need is covered in this readme.
130
+
131
+ Python support can be found at r/LearnPython, YouTube, other forums, and chats.
132
+
133
+ Unreal Engine support can be found on YouTube, their Discord, and their forum.
134
+
135
+ UnrealEnginePython examples, Starcel examples, and the unreal_engine folder (Content/Scripts/unreal_engine, which has the class and function info) should cover just about everything you can do with the plugin. If you are certain there is an issue with the https://github.com/20tab/UnrealEnginePython plugin you can post on the issues tab on GitHub, but you *must* be certain. I will check this every so often.
136
+
137
+ Advanced logging is available.
138
+
139
+ The UE4.27 port of the plugin can be found at https://github.com/HaiyiMei/UnrealEnginePython. I made changes to this source to upgrade it to Python 3.9 and to make it work for my use case.
140
+
141
+ Issues with the Starcel code and new features can be posted on GitHub.
142
+
143
+ I will merge new features and fixes. Feel free to contribute.
144
+
145
+ Anything else can be asked in our Discord. We are a community of volunteers so we may not have answers and may not get back to you, but we will try our best.
146
+
147
+
148
+ ## Are public Starcel servers safe?
149
+ Local use is as safe as local Python. Utilize a whitelist system to stay safe when using servers.
150
+
151
+
152
+ ## How do I use a server?
153
+ You can connect to a server by running the client_travel()/connect() Python function, by changing the _StartClient.bat file, or by opening the console with \` and typing `open <IP>`.
154
+
155
+ If you want to run a local server, LAN, the server console should list a port, local IP, and public IP, or you can use ipconfig. You can share this IP and port with other users on your network. You can port forward this local port in your router to have it available online. You can share your public IP and port with whoever and they will be able to connect. Be very careful sharing your IP and use the whitelist system. Treat this project as downloading and running unsigned code from the internet or giving someone remote desktop access.
156
+
157
+ Python functions can run on the client and server, this is clear from the Python code and can be easily changed. This opens up great possibilities of collaboration using tools like PyCharm's "Code With Me" or by sharing your folders in Windows Explorer's built in OneDrive implementations.
158
+
159
+ Unreal's replication system can be confusing. Clients cannot directly invoke functions on other clients, they must first invoke a call to the server and then the server can run a Multicast RPC. For a replicated actor to exist across all clients in Unreal Engine, it must be spawned on the server.
160
+
161
+ I recommend starting a fresh UE C++ project and getting familiar with Blueprints and maybe also C++ to get a feel for how to use Unreal and its editor.
162
+
163
+ If you want to manually build the dedicated server source, you cannot use UE4.27Chaos from the launcher, you must download the Engine directly from [EpicGame's github branch](https://github.com/EpicGames/UnrealEngine/tree/4.27-chaos), which requires signing up for their developer program. My UE Source folder is ~150GB, whereas the download from the Epic Games Launcher is ~45GB. I needed to add the following lines to my "C:\Program Files\Epic Games\UE_4.27Chaos_Source\Engine\Config\BaseEngine.ini" among a few other fixes for compiling this project.
164
+ ```
165
+ [PlatformPaths]
166
+ UnrealBuildTool=Engine/Binaries/DotNET/UnrealBuildTool.exe
167
+ ```
168
+ You can cook and package your project from the UE4Editor File tab.
169
+
170
+
171
+ ## Linux and Mac?
172
+ Starcel is currently Windows only. It can be compiled on other operating systems, however, this is currently untested. To start, UE, Python, and the UnrealEnginePython plugin are supported in Linux and MacOS. If the project receives support and requests I will port it myself. Feel free to submit a pull request if you upgrade it yourself. 70% of users are on Windows, 13% on Mac, 4% on Linux.
173
+
174
+
175
+ ## Is the program stable?
176
+ Not currently, eventually there will be a stable update.
177
+
178
+
179
+ ## AR/VR integration?
180
+ I am working on integration for AR glasses. Glove-based hand-tracking is in development. If you plan on setting the rotation of the player to a quaternion that comes from a AR/VR device, make sure your quaternion apis match and your coordinate systems match(UE uses left-handed Z-up).
181
+
182
+
183
+ ## Can I make a 2D UI?
184
+ It is not recommended to control any elements in Starcel with a 2D UI. You can build a UI out of 3D elements in the 3D space and make it always display flat on the included screen which I have added as a component to each Pawn's camera. In theory, anything you make in 2D, including websites, you can make exactly the same in 3D. Despite that, UnrealEnginePython has built in support for QT in Engine using Slate, which renders directly on top of the existing Starcel viewport. If you need, you could use Tkinter, QT, etc. to make a 2D UI outside the game window.
185
+
186
+
187
+ ## UE5 and Python upgrade?
188
+ You can use the included interop.py(untested) to help run newer Python versions with this version, but it will be slow and you will have to add workarounds for using functions like begin_play and tick. You will need to have both versions of Python installed. The latest edition of Starcel is written in Python 3.9 and Unreal Engine 4.27Chaos. This likely will not change for a while as Python's C++ bindings have been deprecated and changed in Python 3.10. This could take a month or few to upgrade. An [Unreal Engine 5 upgrade of the UnrealEnginePython plugin](https://github.com/20tab/UnrealEnginePython/pull/880) will require header, module, and api changes. This could take a month to upgrade. If you plan on working on this, you can message me for some info that could help you begin.
189
+
190
+
191
+ ## What happened to the last Starcel and its features?
192
+ It was too buggy and I didn't want new users to be disappointed, so I removed the download link.
193
+
194
+
195
+ ## WIP
196
+ - Tables Python spreadsheets
197
+ - Hotkey editor
198
+ - File explorer, icons, and desktop environment
199
+ - Transparent Windows and Live Wallpaper
200
+ - CLI
201
+ - Multidimensional plotting and graphing
202
+ - Advanced function and question search with live search and history
203
+ - Multiplayer
204
+ - UDCAP VR Glove and AR Glasses Integration
205
+
206
+
207
+ ## What this program isn't
208
+ This is not a 2D User Interface. This is not a 3D Sculputing program, this is not a CAD Kernel, this is not a video editor interface.
209
+
210
+
211
+ ## Why Unreal?
212
+ Unreal is great! It is industry-leading for developing games and in cinema. The Python bindings make this a fully featured rendering engine with quick scripting potential. The rendering system is unmatched, beautiful, and the engine itself is fast. I tested Unity, Panda3D, UPBGE and NVIDIA Omniverse, and many other programs, and they didn't have the features I was looking for.
213
+
214
+
215
+ ## Where did you get the idea?
216
+ I wanted to build a system for multidimensional tables and multidimensional plotting of functions and data. For example, plotting multidimensional weights in LLMs (https://youtu.be/wjZofJX0v4M?&t=813, here the embedding space in GPT-3 is 12,228 dimensional, whereas Kingdon only allows up to 16 dimensions). I wanted to build the final form of computer interaction, by building in 3D we have allowed a space for representing just about any object you will encounter and everything in the world. Using a programming language designed to be human readable was paramount. I wanted something that is as close to the English language as possible while still being useful. Excel is the most used programming language by a large margin, with python being the next. It is very convenient to program in a table, as many data structures, tensors, matrices, arrays, nodes, can be represented as a table.
217
+
218
+
219
+ ## Where does the name "Starcel" come from?
220
+ - In software, the * character is used as a wildcard which could represent literally anything. One of the goals of Starcel is to allow you to run any conceivable command and represent any format of data.
221
+ - If you leave the axiomatically set area you will see your space and actions from a third person view - a single star, or dot, suspended in the void.
222
+ - Starcel runs inside the cells of a spreadsheet.
223
+ - "cel" relates to our player acceleration function. It is intended that Starcel accelerates users and development around the world.
224
+ - We built a function that spawns basis of various dimensions within a spatial dimension. These basis look like stars.
225
+ ![Commands and Features](/Images/DimSelectorOverride.png)
226
+ - You are a Star! *
227
+
228
+
229
+ ## Fun stats
230
+ - Unreal Engine 4 has ~16,000,000 lines of code
231
+ - 20tab/UnrealEnginePython is ~70,000 lines of code
232
+ - starcel-ue4 is ~35,000 lines of Python code and ~2000 lines of C++ code
233
+ - starcel-ue4 was written in 6 months
234
+
235
+
236
+ ## Need to contact me?
237
+ If you need to sponsor the project, you can contact me by email, nick recursion.is.
238
+
239
+
240
+ ## Social
241
+ - https://discord.gg/nAfm6knz
242
+ - https://recursion.is/youtube
243
+
244
+
245
+ ## Contributors
246
+ This project would not have been possible without rdeioris's work on [UnrealEnginePython](https://github.com/20tab/UnrealEnginePython)
247
+
248
+
249
+ # Support the Project
250
+ You can donate on [Paypal](https://www.paypal.com/paypalme/RecursionIs) or [Patreon](https://www.patreon.com/RecursionIs)
251
+
252
+
253
+ ## Would you like to contribute?
254
+ Send as many feature updates and issues as you would like.
255
+
256
+ Although you can work on anything you'd like, here are specific tasks I need help with:
257
+ - Upgrade the Python code to be more Pythonic, maybe inspired by Ursina, and make the unreal_engine functions more user-friendly
258
+ - Integrate [UnrealEnginePython Modus](https://github.com/dfb/UnrealEnginePython/tree/modus)
259
+ - Proper Software Engineering principles refactor — Much of this code is AI generated, and I lost the plot
260
+ - Clean up the Unreal Engine files according to [standards](https://github.com/Allar/ue5-style-guide) and update the Python files to match. Try to migrate blueprints to Python code.
261
+ - Upgrade to the latest version of Unreal Engine or UE4.27-Plus, and Python after the above
262
+ - Panda3D style of object control and Ursina
263
+ - Integrate Starcel as a renderer for Manim
264
+ - AI md files (anthropic, openai, gemini, etc.)
265
+ - Continued server development
266
+ - Someone to create example maps
@@ -0,0 +1,220 @@
1
+ # Starcel <sub><img src="https://raw.githubusercontent.com/recursionis/starcel/master/Images/branding/icon-padded.png" alt="logo"></sub>
2
+ Hi! I'm Nick, the developer of Starcel
3
+
4
+
5
+ ## What is it?
6
+ A Python controlled 3D spreadsheet. A full Unreal Engine 4 instance with Chaos physics. Support for Client and Server. It can be used as a visualization or education tool.
7
+
8
+ Currently, Starcel is an Unreal Engine 4.27Chaos Client and Server which can be controlled with Python 3.9. There is 3D spreadsheet functionality, a Python calculation engine, everything Unreal engine offers, and there are many more features planned. It is very powerful.
9
+
10
+ This project is intended for content creators, hobbyists, developers, spreadsheet users, physicists, engineers, scientists, gamers, unreal engine prototypes, and more.
11
+
12
+
13
+ ## Please [donate](https://www.patreon.com/RecursionIs) to keep this project running!
14
+ You can donate on [Paypal](https://www.paypal.com/paypalme/RecursionIs) or [Patreon](https://www.patreon.com/RecursionIs)
15
+
16
+
17
+ ## Quickstart
18
+ The current release includes the client, the server, and the no-editor for Windows. Each compiled source is ~1GB.
19
+ The full Unreal Engine Starcel source project folder is quite a large download, >50GB. The project files on github are ~1GB, check the .gitignore to see what is missing.
20
+
21
+ You need to use Visual Studio 2019 for compiling ([download community edition](https://aka.ms/vs/16/release/vs_community.exe)). I recommend [PyCharm Community](https://www.jetbrains.com/pycharm/download/?section=windows) for editing until IDE support is added.
22
+
23
+ Compiled versions of Python 3.9 can be downloaded from here https://www.python.org/downloads/release/python-3913/, newer versions of specifically Python 3.9 should work, but need to be compiled from Python source. The unreal_engine package is not installed to Python permanently, but it is installed at runtime, so it does not need to be pip-installed. The `Content/Scripts/unreal_engine` folder includes all necessary stubs and empty classes for intellisense.
24
+
25
+ You can manually install the necessary packages directly using `python.exe -m pip install -r requirements.txt`.
26
+
27
+ The default Unreal Engine map contains a PyActor which loads main.py and the class Main when the map starts up. Both the server and the client will run this file separately. The line ``if KismetSystemLibrary.IsDedicatedServer():`` lets you define client and server specific code. You can create more PyActors or even use Python from the UE console by clicking ` and typing "py.".
28
+
29
+ Use `spawn_pyactor` to create an object that runs a Python class.
30
+
31
+ Create a Text object by double clicking Enter. Once created, you can use =py() to run any Python command.
32
+
33
+ The state of the world is not saved in main.py or elsewhere, you will need to make changes there directly or copy your changes from the world elsewhere to save. This will be changed in the future.
34
+
35
+ Add the following to "C:\Program Files\Epic Games\UE_4.27\Engine\Config\BaseEngine.ini"
36
+ ```
37
+ [PlatformPaths]
38
+ UnrealBuildTool=Engine/Binaries/DotNET/UnrealBuildTool.exe
39
+ ```
40
+
41
+ You may need to set the UE_PYTHON_DIR, PYTHONPATH, and PYTHONHOME environment variables to the location of your python installation, `C:\Users\nicho\AppData\Local\Programs\Python\Python39\` or `C:\Program Files\Python39` for example.
42
+
43
+ You may need to move Python3.dll and python39.dll into C:\Program Files\Epic Games\UE_4.27\Engine\Binaries\ThirdParty\Python3
44
+
45
+ Replace C:\UE_4.27Chaos_Source\Engine\Binaries\ThirdParty\Python3 with a copy of your Python3.9 instance.
46
+
47
+ ## Startup map and mod paks
48
+ You can set which map opens first and which mod `.pak` files load in the ini files. You don't need any command-line arguments.
49
+
50
+ **Startup map:** `Config/DefaultEngine.ini`
51
+ ```ini
52
+ [/Script/EngineSettings.GameMapsSettings]
53
+ GameDefaultMap=/Game/Maps/StaringAtSkyMap.StaringAtSkyMap
54
+ EditorStartupMap=/Game/Maps/StaringAtSkyMap.StaringAtSkyMap
55
+ ```
56
+ You can also change these in the editor under Project Settings → Maps & Modes.
57
+
58
+ **Mod paks:** `Config/DefaultGame.ini`
59
+ ```ini
60
+ [/Script/Starcel9.StarcelPakLoader]
61
+ ; mount every .pak in this folder
62
+ +ModPakDirs=Mods
63
+ ; or list paks one by one
64
+ +ModPaks=Mods/StarcelMapTest1-WindowsNoEditor.pak
65
+ ; optional, overrides GameDefaultMap
66
+ StartupMap=SunTemple
67
+ ```
68
+ Keep comments on their own lines. UE doesn't strip a `;` comment that comes after a value.
69
+ - Relative paths are relative to the project folder. In a packaged build, that's `WindowsNoEditor/Starcel9/`, so the default mods folder is `WindowsNoEditor/Starcel9/Mods/`.
70
+ - A pak can be a full packaged build of another UE 4.27 project, such as `MyMap-WindowsNoEditor.pak`. Its `/Game/...` assets become loadable without overriding Starcel's own files.
71
+ - `StartupMap` takes a short name (`SunTemple`) that is looked up in the mounted paks, or a full path (`/Game/Maps/SunTemple`).
72
+ - To change these settings in a packaged build without repackaging, put the same section in `WindowsNoEditor/Starcel9/Saved/Config/WindowsNoEditor/Game.ini`.
73
+ - Mod paks only load in packaged builds. The editor can't load cooked content.
74
+
75
+ The command line still works and takes priority: `Starcel9.exe SunTemple -ModPak="C:/path/to/MyMap-WindowsNoEditor.pak"` (see `test-pakmap.bat`). A map named on the command line is used instead of `StartupMap`. Paks from `-ModPak` are mounted in addition to the ones in the ini.
76
+
77
+ While the game is running, open the console (\`) and run `Starcel.LoadPakMap "C:/path/to/File.pak" [MapName]`. Blueprints can call `Mount Map Pak` / `Mount Pak And Open Map`.
78
+
79
+ Don't put mod paks in `Content/Paks`. The engine's automatic pak mounting expects paks built from this project, and it would stop the loose (non-pak) game files from loading.
80
+
81
+
82
+ ## Questions, Issues, and Support
83
+ Most everything you will need is covered in this readme.
84
+
85
+ Python support can be found at r/LearnPython, YouTube, other forums, and chats.
86
+
87
+ Unreal Engine support can be found on YouTube, their Discord, and their forum.
88
+
89
+ UnrealEnginePython examples, Starcel examples, and the unreal_engine folder (Content/Scripts/unreal_engine, which has the class and function info) should cover just about everything you can do with the plugin. If you are certain there is an issue with the https://github.com/20tab/UnrealEnginePython plugin you can post on the issues tab on GitHub, but you *must* be certain. I will check this every so often.
90
+
91
+ Advanced logging is available.
92
+
93
+ The UE4.27 port of the plugin can be found at https://github.com/HaiyiMei/UnrealEnginePython. I made changes to this source to upgrade it to Python 3.9 and to make it work for my use case.
94
+
95
+ Issues with the Starcel code and new features can be posted on GitHub.
96
+
97
+ I will merge new features and fixes. Feel free to contribute.
98
+
99
+ Anything else can be asked in our Discord. We are a community of volunteers so we may not have answers and may not get back to you, but we will try our best.
100
+
101
+
102
+ ## Are public Starcel servers safe?
103
+ Local use is as safe as local Python. Utilize a whitelist system to stay safe when using servers.
104
+
105
+
106
+ ## How do I use a server?
107
+ You can connect to a server by running the client_travel()/connect() Python function, by changing the _StartClient.bat file, or by opening the console with \` and typing `open <IP>`.
108
+
109
+ If you want to run a local server, LAN, the server console should list a port, local IP, and public IP, or you can use ipconfig. You can share this IP and port with other users on your network. You can port forward this local port in your router to have it available online. You can share your public IP and port with whoever and they will be able to connect. Be very careful sharing your IP and use the whitelist system. Treat this project as downloading and running unsigned code from the internet or giving someone remote desktop access.
110
+
111
+ Python functions can run on the client and server, this is clear from the Python code and can be easily changed. This opens up great possibilities of collaboration using tools like PyCharm's "Code With Me" or by sharing your folders in Windows Explorer's built in OneDrive implementations.
112
+
113
+ Unreal's replication system can be confusing. Clients cannot directly invoke functions on other clients, they must first invoke a call to the server and then the server can run a Multicast RPC. For a replicated actor to exist across all clients in Unreal Engine, it must be spawned on the server.
114
+
115
+ I recommend starting a fresh UE C++ project and getting familiar with Blueprints and maybe also C++ to get a feel for how to use Unreal and its editor.
116
+
117
+ If you want to manually build the dedicated server source, you cannot use UE4.27Chaos from the launcher, you must download the Engine directly from [EpicGame's github branch](https://github.com/EpicGames/UnrealEngine/tree/4.27-chaos), which requires signing up for their developer program. My UE Source folder is ~150GB, whereas the download from the Epic Games Launcher is ~45GB. I needed to add the following lines to my "C:\Program Files\Epic Games\UE_4.27Chaos_Source\Engine\Config\BaseEngine.ini" among a few other fixes for compiling this project.
118
+ ```
119
+ [PlatformPaths]
120
+ UnrealBuildTool=Engine/Binaries/DotNET/UnrealBuildTool.exe
121
+ ```
122
+ You can cook and package your project from the UE4Editor File tab.
123
+
124
+
125
+ ## Linux and Mac?
126
+ Starcel is currently Windows only. It can be compiled on other operating systems, however, this is currently untested. To start, UE, Python, and the UnrealEnginePython plugin are supported in Linux and MacOS. If the project receives support and requests I will port it myself. Feel free to submit a pull request if you upgrade it yourself. 70% of users are on Windows, 13% on Mac, 4% on Linux.
127
+
128
+
129
+ ## Is the program stable?
130
+ Not currently, eventually there will be a stable update.
131
+
132
+
133
+ ## AR/VR integration?
134
+ I am working on integration for AR glasses. Glove-based hand-tracking is in development. If you plan on setting the rotation of the player to a quaternion that comes from a AR/VR device, make sure your quaternion apis match and your coordinate systems match(UE uses left-handed Z-up).
135
+
136
+
137
+ ## Can I make a 2D UI?
138
+ It is not recommended to control any elements in Starcel with a 2D UI. You can build a UI out of 3D elements in the 3D space and make it always display flat on the included screen which I have added as a component to each Pawn's camera. In theory, anything you make in 2D, including websites, you can make exactly the same in 3D. Despite that, UnrealEnginePython has built in support for QT in Engine using Slate, which renders directly on top of the existing Starcel viewport. If you need, you could use Tkinter, QT, etc. to make a 2D UI outside the game window.
139
+
140
+
141
+ ## UE5 and Python upgrade?
142
+ You can use the included interop.py(untested) to help run newer Python versions with this version, but it will be slow and you will have to add workarounds for using functions like begin_play and tick. You will need to have both versions of Python installed. The latest edition of Starcel is written in Python 3.9 and Unreal Engine 4.27Chaos. This likely will not change for a while as Python's C++ bindings have been deprecated and changed in Python 3.10. This could take a month or few to upgrade. An [Unreal Engine 5 upgrade of the UnrealEnginePython plugin](https://github.com/20tab/UnrealEnginePython/pull/880) will require header, module, and api changes. This could take a month to upgrade. If you plan on working on this, you can message me for some info that could help you begin.
143
+
144
+
145
+ ## What happened to the last Starcel and its features?
146
+ It was too buggy and I didn't want new users to be disappointed, so I removed the download link.
147
+
148
+
149
+ ## WIP
150
+ - Tables Python spreadsheets
151
+ - Hotkey editor
152
+ - File explorer, icons, and desktop environment
153
+ - Transparent Windows and Live Wallpaper
154
+ - CLI
155
+ - Multidimensional plotting and graphing
156
+ - Advanced function and question search with live search and history
157
+ - Multiplayer
158
+ - UDCAP VR Glove and AR Glasses Integration
159
+
160
+
161
+ ## What this program isn't
162
+ This is not a 2D User Interface. This is not a 3D Sculputing program, this is not a CAD Kernel, this is not a video editor interface.
163
+
164
+
165
+ ## Why Unreal?
166
+ Unreal is great! It is industry-leading for developing games and in cinema. The Python bindings make this a fully featured rendering engine with quick scripting potential. The rendering system is unmatched, beautiful, and the engine itself is fast. I tested Unity, Panda3D, UPBGE and NVIDIA Omniverse, and many other programs, and they didn't have the features I was looking for.
167
+
168
+
169
+ ## Where did you get the idea?
170
+ I wanted to build a system for multidimensional tables and multidimensional plotting of functions and data. For example, plotting multidimensional weights in LLMs (https://youtu.be/wjZofJX0v4M?&t=813, here the embedding space in GPT-3 is 12,228 dimensional, whereas Kingdon only allows up to 16 dimensions). I wanted to build the final form of computer interaction, by building in 3D we have allowed a space for representing just about any object you will encounter and everything in the world. Using a programming language designed to be human readable was paramount. I wanted something that is as close to the English language as possible while still being useful. Excel is the most used programming language by a large margin, with python being the next. It is very convenient to program in a table, as many data structures, tensors, matrices, arrays, nodes, can be represented as a table.
171
+
172
+
173
+ ## Where does the name "Starcel" come from?
174
+ - In software, the * character is used as a wildcard which could represent literally anything. One of the goals of Starcel is to allow you to run any conceivable command and represent any format of data.
175
+ - If you leave the axiomatically set area you will see your space and actions from a third person view - a single star, or dot, suspended in the void.
176
+ - Starcel runs inside the cells of a spreadsheet.
177
+ - "cel" relates to our player acceleration function. It is intended that Starcel accelerates users and development around the world.
178
+ - We built a function that spawns basis of various dimensions within a spatial dimension. These basis look like stars.
179
+ ![Commands and Features](/Images/DimSelectorOverride.png)
180
+ - You are a Star! *
181
+
182
+
183
+ ## Fun stats
184
+ - Unreal Engine 4 has ~16,000,000 lines of code
185
+ - 20tab/UnrealEnginePython is ~70,000 lines of code
186
+ - starcel-ue4 is ~35,000 lines of Python code and ~2000 lines of C++ code
187
+ - starcel-ue4 was written in 6 months
188
+
189
+
190
+ ## Need to contact me?
191
+ If you need to sponsor the project, you can contact me by email, nick recursion.is.
192
+
193
+
194
+ ## Social
195
+ - https://discord.gg/nAfm6knz
196
+ - https://recursion.is/youtube
197
+
198
+
199
+ ## Contributors
200
+ This project would not have been possible without rdeioris's work on [UnrealEnginePython](https://github.com/20tab/UnrealEnginePython)
201
+
202
+
203
+ # Support the Project
204
+ You can donate on [Paypal](https://www.paypal.com/paypalme/RecursionIs) or [Patreon](https://www.patreon.com/RecursionIs)
205
+
206
+
207
+ ## Would you like to contribute?
208
+ Send as many feature updates and issues as you would like.
209
+
210
+ Although you can work on anything you'd like, here are specific tasks I need help with:
211
+ - Upgrade the Python code to be more Pythonic, maybe inspired by Ursina, and make the unreal_engine functions more user-friendly
212
+ - Integrate [UnrealEnginePython Modus](https://github.com/dfb/UnrealEnginePython/tree/modus)
213
+ - Proper Software Engineering principles refactor — Much of this code is AI generated, and I lost the plot
214
+ - Clean up the Unreal Engine files according to [standards](https://github.com/Allar/ue5-style-guide) and update the Python files to match. Try to migrate blueprints to Python code.
215
+ - Upgrade to the latest version of Unreal Engine or UE4.27-Plus, and Python after the above
216
+ - Panda3D style of object control and Ursina
217
+ - Integrate Starcel as a renderer for Manim
218
+ - AI md files (anthropic, openai, gemini, etc.)
219
+ - Continued server development
220
+ - Someone to create example maps
@@ -0,0 +1,71 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "starcel"
7
+ dynamic = ["version"]
8
+ description = "A Python-controlled 3D spreadsheet built on Unreal Engine 4. Installs the Python scripts and a launcher that downloads the latest Starcel build from GitHub."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "RecursionIs" }]
13
+ keywords = ["unreal-engine", "spreadsheet", "3d", "visualization", "education"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Win32 (MS Windows)",
17
+ "Intended Audience :: Developers",
18
+ "Intended Audience :: Education",
19
+ "Intended Audience :: Science/Research",
20
+ "License :: Other/Proprietary License",
21
+ "Operating System :: Microsoft :: Windows",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.9",
24
+ "Topic :: Scientific/Engineering :: Visualization",
25
+ ]
26
+ # Mirrors Content/Scripts/requirements.txt
27
+ dependencies = [
28
+ "numpy",
29
+ "sympy",
30
+ "fast-autocomplete[levenshtein]",
31
+ "numba",
32
+ "kingdon",
33
+ "matplotlib",
34
+ "scikit-image",
35
+ "scikit-learn",
36
+ "dill",
37
+ "pystubgen",
38
+ "requests",
39
+ "pywin32; sys_platform == 'win32'",
40
+ "psutil",
41
+ "opencv-python",
42
+ "imageio",
43
+ "pymupdf",
44
+ "mpmath",
45
+ "py-cpuinfo",
46
+ "pynput",
47
+ "wmi; sys_platform == 'win32'",
48
+ "GPUtil",
49
+ "comtypes; sys_platform == 'win32'",
50
+ ]
51
+
52
+ [project.urls]
53
+ Homepage = "https://github.com/recursionis/starcel"
54
+ Source = "https://github.com/recursionis/starcel"
55
+ Releases = "https://github.com/recursionis/starcel/releases"
56
+ Patreon = "https://www.patreon.com/RecursionIs"
57
+
58
+ [project.scripts]
59
+ starcel = "starcel.launcher:main"
60
+
61
+ [tool.hatch.version]
62
+ path = "src/starcel/__init__.py"
63
+
64
+ [tool.hatch.build]
65
+ exclude = ["**/__pycache__", "**/*.pyc"]
66
+
67
+ [tool.hatch.build.targets.wheel]
68
+ packages = ["src/starcel"]
69
+
70
+ [tool.hatch.build.targets.sdist]
71
+ include = ["src/starcel", "README.md", "LICENSE", "pyproject.toml"]
@@ -0,0 +1,12 @@
1
+ """Starcel: a Python-controlled 3D spreadsheet built on Unreal Engine 4.
2
+
3
+ The Unreal build itself (~1.5 GB) is too large for PyPI, so it is downloaded
4
+ from the latest GitHub release the first time you run ``starcel``.
5
+ """
6
+
7
+ from pathlib import Path
8
+
9
+ __version__ = "0.1.0a1"
10
+
11
+ #: Folder with the bundled Starcel Python scripts (Content/Scripts).
12
+ SCRIPTS_DIR = Path(__file__).resolve().parent / "scripts"
@@ -0,0 +1,3 @@
1
+ from starcel.launcher import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,262 @@
1
+ """`starcel` command: download the newest Starcel build from GitHub and run it.
2
+
3
+ starcel update if a newer release exists, then launch
4
+ starcel run [ARGS...] same, passing ARGS to Starcel9.exe
5
+ starcel update only download/update the build
6
+ starcel info show install location and installed release
7
+ starcel scripts print the Content/Scripts folder (--open to open it)
8
+
9
+ Options: --offline (never contact GitHub), --force (re-download),
10
+ --dir PATH (install location; also env STARCEL_HOME).
11
+ Set GITHUB_TOKEN to avoid GitHub API rate limits.
12
+
13
+ The build is installed to Documents\\Starcel. Before an update replaces it,
14
+ the old Content/Scripts folder is copied to Documents\\Starcel\\backups.
15
+ """
16
+
17
+ import argparse
18
+ import json
19
+ import os
20
+ import shutil
21
+ import subprocess
22
+ import sys
23
+ import tempfile
24
+ import time
25
+ import urllib.request
26
+ import zipfile
27
+ from datetime import datetime
28
+ from pathlib import Path, PurePosixPath
29
+
30
+ from starcel import SCRIPTS_DIR, __version__
31
+
32
+ REPO = "recursionis/starcel"
33
+ ASSET_NAME = "WindowsNoEditor.zip"
34
+ EXE_NAME = "Starcel9.exe"
35
+ STATE_FILE = "release.json"
36
+ BACKUPS = "backups"
37
+ SCRIPTS_REL = Path("Starcel9", "Content", "Scripts") # relative to the exe's folder
38
+
39
+
40
+ def documents_dir():
41
+ """The user's Documents folder, following OneDrive/folder redirection."""
42
+ if sys.platform == "win32":
43
+ try:
44
+ import ctypes
45
+ from ctypes import wintypes
46
+
47
+ class GUID(ctypes.Structure):
48
+ _fields_ = [("Data1", wintypes.DWORD), ("Data2", wintypes.WORD),
49
+ ("Data3", wintypes.WORD), ("Data4", ctypes.c_ubyte * 8)]
50
+
51
+ # FOLDERID_Documents {FDD39AD0-238F-46AF-ADB4-6C85480369C7}
52
+ fid = GUID(0xFDD39AD0, 0x238F, 0x46AF,
53
+ (ctypes.c_ubyte * 8)(0xAD, 0xB4, 0x6C, 0x85, 0x48, 0x03, 0x69, 0xC7))
54
+ buf = ctypes.c_wchar_p()
55
+ if ctypes.windll.shell32.SHGetKnownFolderPath(ctypes.byref(fid), 0, None, ctypes.byref(buf)) == 0:
56
+ try:
57
+ return Path(buf.value)
58
+ finally:
59
+ ctypes.windll.ole32.CoTaskMemFree(buf)
60
+ except Exception:
61
+ pass
62
+ return Path.home() / "Documents"
63
+
64
+
65
+ def default_home():
66
+ if os.environ.get("STARCEL_HOME"):
67
+ return Path(os.environ["STARCEL_HOME"])
68
+ return documents_dir() / "Starcel"
69
+
70
+
71
+ def _request(url, accept="application/vnd.github+json"):
72
+ headers = {"User-Agent": "starcel-launcher/" + __version__, "Accept": accept}
73
+ token = os.environ.get("GITHUB_TOKEN")
74
+ if token and url.startswith("https://api.github.com/"):
75
+ headers["Authorization"] = "Bearer " + token
76
+ return urllib.request.Request(url, headers=headers)
77
+
78
+
79
+ def latest_release():
80
+ """Newest published (non-draft) release that has a .zip build asset.
81
+
82
+ Pre-releases count too, since Starcel is published as alpha builds.
83
+ """
84
+ url = "https://api.github.com/repos/%s/releases?per_page=20" % REPO
85
+ with urllib.request.urlopen(_request(url), timeout=30) as resp:
86
+ releases = json.load(resp)
87
+ releases = [r for r in releases if not r.get("draft")]
88
+ releases.sort(key=lambda r: r.get("published_at") or "", reverse=True)
89
+ for rel in releases:
90
+ zips = [a for a in rel.get("assets", []) if a["name"].lower().endswith(".zip")]
91
+ if not zips:
92
+ continue
93
+ asset = next((a for a in zips if a["name"] == ASSET_NAME), zips[0])
94
+ return {
95
+ "tag": rel["tag_name"],
96
+ "name": rel.get("name") or rel["tag_name"],
97
+ "asset_id": asset["id"],
98
+ "asset_name": asset["name"],
99
+ "updated_at": asset["updated_at"],
100
+ "size": asset["size"],
101
+ "url": asset["browser_download_url"],
102
+ }
103
+ raise RuntimeError("No release with a .zip build found at https://github.com/%s/releases" % REPO)
104
+
105
+
106
+ def read_state(home):
107
+ try:
108
+ return json.loads((home / STATE_FILE).read_text(encoding="utf-8"))
109
+ except (OSError, ValueError):
110
+ return None
111
+
112
+
113
+ def is_current(state, release):
114
+ return bool(state) and all(state.get(k) == release[k] for k in ("tag", "asset_id", "updated_at"))
115
+
116
+
117
+ def _download(url, dest, size):
118
+ with urllib.request.urlopen(_request(url, accept="application/octet-stream"), timeout=60) as resp, \
119
+ open(dest, "wb") as out:
120
+ total = size or int(resp.headers.get("Content-Length") or 0)
121
+ done, last = 0, 0.0
122
+ while True:
123
+ chunk = resp.read(1 << 20)
124
+ if not chunk:
125
+ break
126
+ out.write(chunk)
127
+ done += len(chunk)
128
+ now = time.time()
129
+ if now - last > 0.5:
130
+ last = now
131
+ pct = " (%d%%)" % (done * 100 // total) if total else ""
132
+ sys.stderr.write("\r %.0f / %.0f MB%s " % (done / 1e6, total / 1e6, pct))
133
+ sys.stderr.flush()
134
+ sys.stderr.write("\n")
135
+
136
+
137
+ def _safe_extract(zip_path, dest):
138
+ with zipfile.ZipFile(zip_path) as zf:
139
+ for info in zf.infolist():
140
+ rel = PurePosixPath(info.filename)
141
+ if rel.is_absolute() or ".." in rel.parts or ":" in info.filename:
142
+ raise RuntimeError("Refusing unsafe path in archive: " + info.filename)
143
+ zf.extractall(dest)
144
+
145
+
146
+ def find_exe(home):
147
+ for candidate in (home / "WindowsNoEditor" / EXE_NAME, home / EXE_NAME):
148
+ if candidate.is_file():
149
+ return candidate
150
+ if not home.is_dir():
151
+ return None
152
+ hits = [p for p in home.rglob(EXE_NAME)
153
+ if BACKUPS not in p.relative_to(home).parts and not p.relative_to(home).parts[0].startswith(".dl-")]
154
+ hits.sort(key=lambda p: len(p.parts))
155
+ return hits[0] if hits else None
156
+
157
+
158
+ def scripts_dir(home):
159
+ exe = find_exe(home)
160
+ return exe.parent / SCRIPTS_REL if exe else None
161
+
162
+
163
+ def backup_scripts(home, state):
164
+ """Copy the installed Content/Scripts to backups/ so user edits survive updates."""
165
+ src = scripts_dir(home)
166
+ if not src or not src.is_dir():
167
+ return None
168
+ label = (state or {}).get("tag", "unknown")
169
+ dest = home / BACKUPS / ("Scripts-%s-%s" % (label, datetime.now().strftime("%Y%m%d-%H%M%S")))
170
+ shutil.copytree(str(src), str(dest), ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
171
+ return dest
172
+
173
+
174
+ def install(home, release):
175
+ home.mkdir(parents=True, exist_ok=True)
176
+ print("Downloading Starcel %s (%s, %.0f MB)..." % (release["name"], release["asset_name"], release["size"] / 1e6))
177
+ with tempfile.TemporaryDirectory(dir=str(home), prefix=".dl-") as tmp:
178
+ tmp = Path(tmp)
179
+ zip_path = tmp / release["asset_name"]
180
+ _download(release["url"], zip_path, release["size"])
181
+ print("Extracting...")
182
+ staging = tmp / "build"
183
+ _safe_extract(zip_path, staging)
184
+ zip_path.unlink()
185
+
186
+ backup = backup_scripts(home, read_state(home))
187
+ if backup:
188
+ print("Backed up your previous Content/Scripts to", backup)
189
+ for item in staging.iterdir():
190
+ target = home / item.name
191
+ if item.name in (BACKUPS, STATE_FILE):
192
+ continue
193
+ if target.is_dir():
194
+ shutil.rmtree(target)
195
+ elif target.exists():
196
+ target.unlink()
197
+ shutil.move(str(item), str(target))
198
+ (home / STATE_FILE).write_text(json.dumps(release, indent=2), encoding="utf-8")
199
+ print("Installed to", home)
200
+
201
+
202
+ def ensure_build(home, offline=False, force=False):
203
+ if offline:
204
+ if not find_exe(home):
205
+ raise SystemExit("No Starcel build installed in %s; run without --offline first." % home)
206
+ return
207
+ try:
208
+ release = latest_release()
209
+ except Exception as exc: # network / API errors: fall back to what we have
210
+ if find_exe(home):
211
+ print("Could not check GitHub for updates (%s); using installed build." % exc, file=sys.stderr)
212
+ return
213
+ raise SystemExit("Could not reach GitHub to download Starcel: %s" % exc)
214
+ if force or not is_current(read_state(home), release) or not find_exe(home):
215
+ install(home, release)
216
+ else:
217
+ print("Starcel %s is up to date." % release["name"])
218
+
219
+
220
+ def main(argv=None):
221
+ ap = argparse.ArgumentParser(prog="starcel", description=__doc__,
222
+ formatter_class=argparse.RawDescriptionHelpFormatter)
223
+ ap.add_argument("command", nargs="?", default="run", choices=["run", "update", "info", "scripts"])
224
+ ap.add_argument("--offline", action="store_true", help="don't contact GitHub")
225
+ ap.add_argument("--force", action="store_true", help="re-download even if up to date")
226
+ ap.add_argument("--open", action="store_true", help="with `scripts`: open the folder in Explorer")
227
+ ap.add_argument("--dir", type=Path, default=None, help="install location (default: %s)" % default_home())
228
+ ap.add_argument("--version", action="version", version="starcel " + __version__)
229
+ args, extra = ap.parse_known_args(argv)
230
+ home = args.dir or default_home()
231
+
232
+ if args.command == "scripts":
233
+ folder = scripts_dir(home) or SCRIPTS_DIR
234
+ print(folder)
235
+ if args.open and sys.platform == "win32":
236
+ os.startfile(str(folder))
237
+ return 0
238
+ if args.command == "info":
239
+ state = read_state(home)
240
+ print("Package version :", __version__)
241
+ print("Install dir :", home)
242
+ print("Installed build :", (state or {}).get("name", "none"))
243
+ print("Executable :", find_exe(home) or "not installed")
244
+ print("Scripts folder :", scripts_dir(home) or "not installed")
245
+ print("Bundled scripts :", SCRIPTS_DIR)
246
+ return 0
247
+
248
+ ensure_build(home, offline=args.offline, force=args.force)
249
+ if args.command == "update":
250
+ return 0
251
+
252
+ exe = find_exe(home)
253
+ if exe is None:
254
+ raise SystemExit("%s not found in downloaded build at %s" % (EXE_NAME, home))
255
+ if sys.platform != "win32":
256
+ raise SystemExit("Starcel currently ships as a Windows build only: %s" % exe)
257
+ print("Launching", exe)
258
+ return subprocess.call([str(exe)] + extra, cwd=str(exe.parent))
259
+
260
+
261
+ if __name__ == "__main__":
262
+ raise SystemExit(main())