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.
- starcel-0.1.0a1/.gitignore +5 -0
- starcel-0.1.0a1/LICENSE +173 -0
- starcel-0.1.0a1/PKG-INFO +266 -0
- starcel-0.1.0a1/README.md +220 -0
- starcel-0.1.0a1/pyproject.toml +71 -0
- starcel-0.1.0a1/src/starcel/__init__.py +12 -0
- starcel-0.1.0a1/src/starcel/__main__.py +3 -0
- starcel-0.1.0a1/src/starcel/launcher.py +262 -0
starcel-0.1.0a1/LICENSE
ADDED
|
@@ -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
|
starcel-0.1.0a1/PKG-INFO
ADDED
|
@@ -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
|
+

|
|
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
|
+

|
|
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,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())
|